This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Syntactic sugar and docco revamp for GTY(()) markers
- From: Zack Weinberg <zack at codesourcery dot com>
- To: gcc-patches at gcc dot gnu dot org
- Date: Tue, 30 Mar 2004 11:22:52 -0800
- Subject: Syntactic sugar and docco revamp for GTY(()) markers
This patch adds two kinds of syntactic sugar to GTY(()) markers, and
also includes a major documentation rewrite. The sugar: First,
for options that don't take an argument, you can now leave out the
argument: GTY((skip)) instead of GTY((skip(""))). Second, C-style
string constant concatenation is now supported, so lengthy expressions
can be split over multiple lines.
I converted all the no-argument options to the shorter form; I haven't
made any use of the string concatenation feature.
bootstrapped i686-linux, applied mainline.
zw
gcc:
* gengtype.c (create_option): New function.
* gengtype.h: Prototype it.
* gengtype-yacc.y (stringseq): New rule.
(option): Use create_option. Add new bare ID production. Use
stringseq, not STRING directly.
* alias.c, bitmap.c, c-decl.c, cgraph.h, cpplib.h, cselib.h
* dwarf2out.c, emit-rtl.c, function.h, lists.c, tree.h
* varray.h, config/alpha/alpha.c, cp/name-lookup.c, cp/parser.c
* f/com.c, java/builtins.c, java/expr.c, java/jcf.h, java/parse.h:
Use new shorter form of GTY markers.
* doc/gty.texi: Rewrite.
include:
* hashtab.h, splay-tree.h: Use new shorter form of GTY markers.
===================================================================
Index: gengtype-yacc.y
--- gengtype-yacc.y 29 Apr 2003 18:51:38 -0000 1.9
+++ gengtype-yacc.y 30 Mar 2004 18:55:44 -0000
@@ -57,7 +57,7 @@ Software Foundation, 59 Temple Place - S
%type <p> struct_fields yacc_ids yacc_typematch
%type <t> type lasttype
%type <o> optionsopt options option optionseq optionseqopt
-%type <s> type_option
+%type <s> type_option stringseq
%%
@@ -268,21 +268,12 @@ type_option : ALIAS
{ $$ = $1; }
;
-option: type_option '(' type ')'
- {
- options_p o = xmalloc (sizeof (*o));
- o->name = $1;
- o->info = adjust_field_type ($3, NULL);
- $$ = o;
- }
- | ID '(' STRING ')'
- {
- options_p o = xmalloc (sizeof (*o));
- o->name = $1;
- o->info = (void *)$3;
- $$ = o;
- }
- ;
+option: ID
+ { $$ = create_option ($1, (void *)""); }
+ | ID '(' stringseq ')'
+ { $$ = create_option ($1, (void *)$3); }
+ | type_option '(' type ')'
+ { $$ = create_option ($1, adjust_field_type ($3, NULL)); }
optionseq: option
{
@@ -299,4 +290,16 @@ optionseq: option
optionseqopt: { $$ = NULL; }
| optionseq { $$ = $1; }
;
+
+stringseq: STRING
+ { $$ = $1; }
+ | stringseq STRING
+ {
+ size_t l1 = strlen ($1);
+ size_t l2 = strlen ($2);
+ char *s = xrealloc ((char *)$1, l1 + l2 + 1);
+ memcpy (s + l1, $2, l2 + 1);
+ free ((void *)$2);
+ $$ = s;
+ }
%%
===================================================================
Index: gengtype.c
--- gengtype.c 6 Feb 2004 20:03:42 -0000 1.46
+++ gengtype.c 30 Mar 2004 18:55:44 -0000
@@ -308,6 +308,16 @@ create_array (type_p t, const char *len)
return v;
}
+/* Return an options structure with name NAME and info INFO. */
+options_p
+create_option (const char *name, void *info)
+{
+ options_p o = xmalloc (sizeof (*o));
+ o->name = name;
+ o->info = info;
+ return o;
+}
+
/* Add a variable named S of type T with options O defined at POS,
to `variables'. */
===================================================================
Index: gengtype.h
--- gengtype.h 21 Jan 2004 20:40:01 -0000 1.9
+++ gengtype.h 30 Mar 2004 18:55:44 -0000
@@ -130,6 +130,7 @@ extern type_p find_structure (const char
extern type_p create_scalar_type (const char *name, size_t name_len);
extern type_p create_pointer (type_p t);
extern type_p create_array (type_p t, const char *len);
+extern options_p create_option (const char *name, void *info);
extern type_p adjust_field_type (type_p, options_p);
extern void note_variable (const char *s, type_p t, options_p o,
struct fileloc *pos);
===================================================================
Index: alias.c
--- alias.c 25 Mar 2004 00:58:56 -0000 1.223
+++ alias.c 30 Mar 2004 18:55:43 -0000
@@ -163,7 +163,7 @@ static rtx *new_reg_base_value;
/* We preserve the copy of old array around to avoid amount of garbage
produced. About 8% of garbage produced were attributed to this
array. */
-static GTY((deletable (""))) varray_type old_reg_base_value;
+static GTY((deletable)) varray_type old_reg_base_value;
/* Static hunks of RTL used by the aliasing code; these are initialized
once per function to avoid unnecessary RTL allocations. */
===================================================================
Index: bitmap.c
--- bitmap.c 21 Dec 2003 14:08:32 -0000 1.47
+++ bitmap.c 30 Mar 2004 18:55:43 -0000
@@ -44,7 +44,7 @@ static int bitmap_obstack_init = FALSE;
/* Global data */
bitmap_element bitmap_zero_bits; /* An element of all zero bits. */
static bitmap_element *bitmap_free; /* Freelist of bitmap elements. */
-static GTY((deletable (""))) bitmap_element *bitmap_ggc_free;
+static GTY((deletable)) bitmap_element *bitmap_ggc_free;
static void bitmap_elem_to_freelist (bitmap, bitmap_element *);
static void bitmap_element_free (bitmap, bitmap_element *);
===================================================================
Index: c-decl.c
--- c-decl.c 28 Mar 2004 17:45:53 -0000 1.491
+++ c-decl.c 30 Mar 2004 18:55:44 -0000
@@ -317,11 +317,11 @@ static GTY(()) struct c_scope *external_
/* A chain of c_scope structures awaiting reuse. */
-static GTY((deletable (""))) struct c_scope *scope_freelist;
+static GTY((deletable)) struct c_scope *scope_freelist;
/* A chain of c_binding structures awaiting reuse. */
-static GTY((deletable (""))) struct c_binding *binding_freelist;
+static GTY((deletable)) struct c_binding *binding_freelist;
/* Append VAR to LIST in scope SCOPE. */
#define SCOPE_LIST_APPEND(scope, list, decl) do { \
===================================================================
Index: cgraph.h
--- cgraph.h 21 Jan 2004 20:39:52 -0000 1.27
+++ cgraph.h 30 Mar 2004 18:55:44 -0000
@@ -97,7 +97,7 @@ struct cgraph_node GTY((chain_next ("%h.
struct cgraph_node *next_nested;
/* Pointer to the next function in cgraph_nodes_queue. */
struct cgraph_node *next_needed;
- PTR GTY ((skip (""))) aux;
+ PTR GTY ((skip)) aux;
struct cgraph_local_info local;
struct cgraph_global_info global;
===================================================================
Index: cpplib.h
--- cpplib.h 4 Mar 2004 00:18:45 -0000 1.279
+++ cpplib.h 30 Mar 2004 18:55:44 -0000
@@ -508,9 +508,9 @@ struct cpp_hashnode GTY(())
union _cpp_hashnode_value
{
/* If a macro. */
- cpp_macro * GTY((skip (""))) macro;
+ cpp_macro * GTY((skip)) macro;
/* Answers to an assertion. */
- struct answer * GTY ((skip (""))) answers;
+ struct answer * GTY ((skip)) answers;
/* Code for a builtin macro. */
enum builtin_type GTY ((tag ("1"))) builtin;
/* Macro argument index. */
===================================================================
Index: cselib.h
--- cselib.h 4 Mar 2004 16:28:47 -0000 1.13
+++ cselib.h 30 Mar 2004 18:55:44 -0000
@@ -29,7 +29,7 @@ typedef struct cselib_val_struct GTY(())
/* A VALUE rtx that points back to this structure. */
rtx GTY ((tag ("1"))) val_rtx;
/* Used to keep a list of free cselib_val structures. */
- struct cselib_val_struct * GTY ((skip (""))) next_free;
+ struct cselib_val_struct * GTY ((skip)) next_free;
} GTY ((desc ("1"))) u;
/* All rtl expressions that hold this value at the current time during a
===================================================================
Index: dwarf2out.c
--- dwarf2out.c 22 Mar 2004 20:56:59 -0000 1.509
+++ dwarf2out.c 30 Mar 2004 18:55:44 -0000
@@ -2419,7 +2419,7 @@ typedef struct dw_val_struct GTY(())
unsigned HOST_WIDE_INT GTY ((tag ("dw_val_class_offset"))) val_offset;
dw_loc_list_ref GTY ((tag ("dw_val_class_loc_list"))) val_loc_list;
dw_loc_descr_ref GTY ((tag ("dw_val_class_loc"))) val_loc;
- HOST_WIDE_INT GTY ((default (""))) val_int;
+ HOST_WIDE_INT GTY ((default)) val_int;
unsigned HOST_WIDE_INT GTY ((tag ("dw_val_class_unsigned_const"))) val_unsigned;
dw_long_long_const GTY ((tag ("dw_val_class_long_long"))) val_long_long;
dw_vec_const GTY ((tag ("dw_val_class_vec"))) val_vec;
===================================================================
Index: emit-rtl.c
--- emit-rtl.c 22 Mar 2004 00:40:43 -0000 1.386
+++ emit-rtl.c 30 Mar 2004 18:55:44 -0000
@@ -4751,7 +4751,7 @@ emit (rtx x)
}
/* Space for free sequence stack entries. */
-static GTY ((deletable (""))) struct sequence_stack *free_sequence_stack;
+static GTY ((deletable)) struct sequence_stack *free_sequence_stack;
/* Begin emitting insns to a sequence which can be packaged in an
RTL_EXPR. If this sequence will contain something that might cause
@@ -5483,7 +5483,7 @@ emit_copy_of_insn_after (rtx insn, rtx a
return new;
}
-static GTY((deletable(""))) rtx hard_reg_clobbers [NUM_MACHINE_MODES][FIRST_PSEUDO_REGISTER];
+static GTY((deletable)) rtx hard_reg_clobbers [NUM_MACHINE_MODES][FIRST_PSEUDO_REGISTER];
rtx
gen_hard_reg_clobber (enum machine_mode mode, unsigned int regno)
{
===================================================================
Index: function.h
--- function.h 4 Feb 2004 12:22:32 -0000 1.110
+++ function.h 30 Mar 2004 18:55:44 -0000
@@ -377,7 +377,7 @@ struct function GTY(())
/* For md files. */
/* tm.h can use this to store whatever it likes. */
- struct machine_function * GTY ((maybe_undef (""))) machine;
+ struct machine_function * GTY ((maybe_undef)) machine;
/* The largest alignment of slot allocated on the stack. */
int stack_alignment_needed;
/* Preferred alignment of the end of stack frame. */
===================================================================
Index: lists.c
--- lists.c 16 Jun 2003 11:30:21 -0000 1.16
+++ lists.c 30 Mar 2004 18:55:44 -0000
@@ -32,10 +32,10 @@ static void free_list (rtx *, rtx *);
/* Functions for maintaining cache-able lists of EXPR_LIST and INSN_LISTs. */
/* An INSN_LIST containing all INSN_LISTs allocated but currently unused. */
-static GTY ((deletable (""))) rtx unused_insn_list;
+static GTY ((deletable)) rtx unused_insn_list;
/* An EXPR_LIST containing all EXPR_LISTs allocated but currently unused. */
-static GTY ((deletable (""))) rtx unused_expr_list;
+static GTY ((deletable)) rtx unused_expr_list;
/* This function will free an entire list of either EXPR_LIST or INSN_LIST
===================================================================
Index: tree.h
--- tree.h 23 Mar 2004 20:43:39 -0000 1.483
+++ tree.h 30 Mar 2004 18:55:45 -0000
@@ -1831,7 +1831,7 @@ struct tree_decl GTY(())
unsigned int align : 24;
unsigned int off_align : 8;
} a;
- } GTY ((skip (""))) u1;
+ } GTY ((skip)) u1;
tree size_unit;
tree name;
===================================================================
Index: varray.h
--- varray.h 21 Jan 2004 20:40:04 -0000 1.35
+++ varray.h 30 Mar 2004 18:55:45 -0000
@@ -106,7 +106,7 @@ typedef union varray_data_tag GTY (()) {
tag ("VARRAY_DATA_HINT"))) hint[1];
unsigned HOST_WIDE_INT GTY ((length ("%0.num_elements"),
tag ("VARRAY_DATA_UHINT"))) uhint[1];
- PTR GTY ((length ("%0.num_elements"), use_param (""),
+ PTR GTY ((length ("%0.num_elements"), use_param,
tag ("VARRAY_DATA_GENERIC"))) generic[1];
char *GTY ((length ("%0.num_elements"),
tag ("VARRAY_DATA_CPTR"))) cptr[1];
@@ -118,11 +118,11 @@ typedef union varray_data_tag GTY (()) {
tag ("VARRAY_DATA_TREE"))) tree[1];
struct bitmap_head_def *GTY ((length ("%0.num_elements"),
tag ("VARRAY_DATA_BITMAP"))) bitmap[1];
- struct reg_info_def *GTY ((length ("%0.num_elements"), skip (""),
+ struct reg_info_def *GTY ((length ("%0.num_elements"), skip,
tag ("VARRAY_DATA_REG"))) reg[1];
struct const_equiv_data GTY ((length ("%0.num_elements"),
tag ("VARRAY_DATA_CONST_EQUIV"))) const_equiv[1];
- struct basic_block_def *GTY ((length ("%0.num_elements"), skip (""),
+ struct basic_block_def *GTY ((length ("%0.num_elements"), skip,
tag ("VARRAY_DATA_BB"))) bb[1];
struct elt_list *GTY ((length ("%0.num_elements"),
tag ("VARRAY_DATA_TE"))) te[1];
===================================================================
Index: config/alpha/alpha.c
--- config/alpha/alpha.c 12 Mar 2004 10:03:07 -0000 1.359
+++ config/alpha/alpha.c 30 Mar 2004 18:55:45 -0000
@@ -3567,8 +3567,8 @@ alpha_split_conditional_move (enum rtx_c
struct xfloating_op GTY(())
{
const enum rtx_code code;
- const char *const GTY((skip(""))) osf_func;
- const char *const GTY((skip(""))) vms_func;
+ const char *const GTY((skip)) osf_func;
+ const char *const GTY((skip)) vms_func;
rtx libcall;
};
===================================================================
Index: cp/name-lookup.c
--- cp/name-lookup.c 20 Mar 2004 00:18:17 -0000 1.48
+++ cp/name-lookup.c 30 Mar 2004 18:55:45 -0000
@@ -61,7 +61,7 @@ GTY(()) tree anonymous_namespace_name;
/* A free list of "binding_entry"s awaiting for re-use. */
-static GTY((deletable(""))) binding_entry free_binding_entry = NULL;
+static GTY((deletable)) binding_entry free_binding_entry = NULL;
/* Create a binding_entry object for (NAME, TYPE). */
@@ -317,7 +317,7 @@ binding_table_foreach (binding_table tab
/* A free list of "cxx_binding"s, connected by their PREVIOUS. */
-static GTY((deletable (""))) cxx_binding *free_bindings;
+static GTY((deletable)) cxx_binding *free_bindings;
/* Zero out a cxx_binding pointed to by B. */
#define cxx_binding_clear(B) memset ((B), 0, sizeof (cxx_binding))
@@ -1232,7 +1232,7 @@ namespace_scope_ht_size (tree ns)
/* A chain of binding_level structures awaiting reuse. */
-static GTY((deletable (""))) struct cp_binding_level *free_binding_level;
+static GTY((deletable)) struct cp_binding_level *free_binding_level;
/* Create a new KIND scope and make it the top of the active scopes stack.
ENTITY is the scope of the associated C++ entity (namespace, class,
===================================================================
Index: cp/parser.c
--- cp/parser.c 23 Mar 2004 23:47:48 -0000 1.187
+++ cp/parser.c 30 Mar 2004 18:55:46 -0000
@@ -167,19 +167,19 @@ typedef struct cp_lexer GTY (())
/* The memory allocated for the buffer. Never NULL. */
cp_token * GTY ((length ("(%h.buffer_end - %h.buffer)"))) buffer;
/* A pointer just past the end of the memory allocated for the buffer. */
- cp_token * GTY ((skip (""))) buffer_end;
+ cp_token * GTY ((skip)) buffer_end;
/* The first valid token in the buffer, or NULL if none. */
- cp_token * GTY ((skip (""))) first_token;
+ cp_token * GTY ((skip)) first_token;
/* The next available token. If NEXT_TOKEN is NULL, then there are
no more available tokens. */
- cp_token * GTY ((skip (""))) next_token;
+ cp_token * GTY ((skip)) next_token;
/* A pointer just past the last available token. If FIRST_TOKEN is
NULL, however, there are no available tokens, and then this
location is simply the place in which the next token read will be
placed. If LAST_TOKEN == FIRST_TOKEN, then the buffer is full.
When the LAST_TOKEN == BUFFER, then the last token is at the
highest memory address in the BUFFER. */
- cp_token * GTY ((skip (""))) last_token;
+ cp_token * GTY ((skip)) last_token;
/* A stack indicating positions at which cp_lexer_save_tokens was
called. The top entry is the most recent position at which we
@@ -1126,7 +1126,7 @@ static cp_parser_context *cp_parser_cont
/* Class variables. */
-static GTY((deletable (""))) cp_parser_context* cp_parser_context_free_list;
+static GTY((deletable)) cp_parser_context* cp_parser_context_free_list;
/* Constructors and destructors. */
===================================================================
Index: f/com.c
--- f/com.c 17 Feb 2004 21:33:42 -0000 1.223
+++ f/com.c 30 Mar 2004 18:55:46 -0000
@@ -558,7 +558,7 @@ static GTY(()) struct f_binding_level *c
/* A chain of binding_level structures awaiting reuse. */
-static GTY((deletable (""))) struct f_binding_level *free_binding_level;
+static GTY((deletable)) struct f_binding_level *free_binding_level;
/* The outermost binding level, for names of file scope.
This is created when the compiler is started and exists
===================================================================
Index: java/builtins.c
--- java/builtins.c 5 Oct 2003 02:52:33 -0000 1.21
+++ java/builtins.c 30 Mar 2004 18:55:46 -0000
@@ -65,7 +65,7 @@ struct builtin_record GTY(())
{
union string_or_tree GTY ((desc ("1"))) class_name;
union string_or_tree GTY ((desc ("1"))) method_name;
- builtin_creator_function * GTY((skip (""))) creator;
+ builtin_creator_function * GTY((skip)) creator;
enum built_in_function builtin_code;
};
===================================================================
Index: java/expr.c
--- java/expr.c 5 Feb 2004 22:07:32 -0000 1.184
+++ java/expr.c 30 Mar 2004 18:55:46 -0000
@@ -126,7 +126,7 @@ int always_initialize_class_p;
static GTY(()) tree quick_stack;
/* A free-list of unused permanent TREE_LIST nodes. */
-static GTY((deletable (""))) tree tree_list_free_list;
+static GTY((deletable)) tree tree_list_free_list;
/* The stack pointer of the Java virtual machine.
This does include the size of the quick_stack. */
===================================================================
Index: java/jcf.h
--- java/jcf.h 5 Oct 2003 02:52:33 -0000 1.41
+++ java/jcf.h 30 Mar 2004 18:55:46 -0000
@@ -102,19 +102,19 @@ struct ZipDirectory;
/* JCF encapsulates the state of reading a Java Class File. */
typedef struct JCF GTY(()) {
- unsigned char * GTY ((skip (""))) buffer;
- unsigned char * GTY ((skip (""))) buffer_end;
- unsigned char * GTY ((skip (""))) read_ptr;
- unsigned char * GTY ((skip (""))) read_end;
+ unsigned char * GTY ((skip)) buffer;
+ unsigned char * GTY ((skip)) buffer_end;
+ unsigned char * GTY ((skip)) read_ptr;
+ unsigned char * GTY ((skip)) read_end;
int java_source : 1;
int right_zip : 1;
int finished : 1;
jcf_filbuf_t filbuf;
- PTR GTY ((skip (""))) read_state;
+ PTR GTY ((skip)) read_state;
const char *filename;
const char *classname;
/* Directory entry where it was found. */
- struct ZipDirectory * GTY ((skip (""))) zipd;
+ struct ZipDirectory * GTY ((skip)) zipd;
JCF_u2 access_flags;
JCF_u2 this_class;
JCF_u2 super_class;
===================================================================
Index: java/parse.h
--- java/parse.h 27 Feb 2004 14:50:47 -0000 1.95
+++ java/parse.h 30 Mar 2004 18:55:46 -0000
@@ -728,10 +728,10 @@ struct parser_ctxt GTY(()) {
const char *filename; /* Current filename */
struct parser_ctxt *next;
- java_lexer * GTY((skip (""))) lexer; /* Current lexer state */
+ java_lexer * GTY((skip)) lexer; /* Current lexer state */
char marker_begining; /* Marker. Should be a sub-struct */
- struct java_line * GTY ((skip (""))) p_line; /* Previous line */
- struct java_line * GTY ((skip (""))) c_line; /* Current line */
+ struct java_line * GTY ((skip)) p_line; /* Previous line */
+ struct java_line * GTY ((skip)) c_line; /* Current line */
java_lc elc; /* Error's line column info */
int ccb_indent; /* Keep track of {} indent, lexer */
int first_ccb_indent1; /* First { at ident level 1 */
@@ -739,7 +739,7 @@ struct parser_ctxt GTY(()) {
int parser_ccb_indent; /* Keep track of {} indent, parser */
int osb_depth; /* Current depth of [ in an expression */
int osb_limit; /* Limit of this depth */
- int * GTY ((skip (""))) osb_number; /* Keep track of ['s */
+ int * GTY ((skip)) osb_number; /* Keep track of ['s */
int lineno; /* Current lineno */
char marker_end; /* End marker. Should be a sub-struct */
@@ -774,7 +774,7 @@ struct parser_ctxt GTY(()) {
/* These two lists won't survive file traversal */
tree class_list; /* List of classes in a CU */
- jdeplist * GTY((skip (""))) classd_list; /* Classe dependencies in a CU */
+ jdeplist * GTY((skip)) classd_list; /* Classe dependencies in a CU */
tree current_parsed_class; /* Class currently parsed */
tree current_parsed_class_un; /* Curr. parsed class unqualified name */
===================================================================
Index: doc/gty.texi
--- doc/gty.texi 25 Jan 2004 03:28:25 -0000 1.14
+++ doc/gty.texi 30 Mar 2004 18:55:46 -0000
@@ -13,37 +13,26 @@ involve determining information about GC
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.
+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 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(())}
+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
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(())}
-When the parameter is a string, often it is a fragment of C code. Three
-special escapes may be available:
+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. 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
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 bei
@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 rea
@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
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
@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
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
===================================================================
Index: hashtab.h
--- hashtab.h 7 May 2003 20:30:32 -0000 1.19
+++ hashtab.h 30 Mar 2004 19:05:16 -0000
@@ -99,7 +99,7 @@ struct htab GTY(())
htab_del del_f;
/* Table itself. */
- PTR * GTY ((use_param (""), length ("%h.size"))) entries;
+ PTR * GTY ((use_param, length ("%h.size"))) entries;
/* Current size (in entries) of the hash table */
size_t size;
@@ -123,7 +123,7 @@ struct htab GTY(())
htab_free free_f;
/* Alternate allocate/free functions, which take an extra argument. */
- PTR GTY((skip (""))) alloc_arg;
+ PTR GTY((skip)) alloc_arg;
htab_alloc_with_arg alloc_with_arg_f;
htab_free_with_arg free_with_arg_f;
};
===================================================================
Index: splay-tree.h
--- splay-tree.h 10 Jan 2003 02:22:34 -0000 1.18
+++ splay-tree.h 30 Mar 2004 19:05:16 -0000
@@ -81,21 +81,21 @@ typedef void (*splay_tree_deallocate_fn)
struct splay_tree_node_s GTY(())
{
/* The key. */
- splay_tree_key GTY ((use_param1 (""))) key;
+ splay_tree_key GTY ((use_param1)) key;
/* The value. */
- splay_tree_value GTY ((use_param2 (""))) value;
+ splay_tree_value GTY ((use_param2)) value;
/* The left and right children, respectively. */
- splay_tree_node GTY ((use_params (""))) left;
- splay_tree_node GTY ((use_params (""))) right;
+ splay_tree_node GTY ((use_params)) left;
+ splay_tree_node GTY ((use_params)) right;
};
/* The splay tree itself. */
struct splay_tree_s GTY(())
{
/* The root of the tree. */
- splay_tree_node GTY ((use_params (""))) root;
+ splay_tree_node GTY ((use_params)) root;
/* The comparision function. */
splay_tree_compare_fn comp;
@@ -109,7 +109,7 @@ struct splay_tree_s GTY(())
/* Allocate/free functions, and a data pointer to pass to them. */
splay_tree_allocate_fn allocate;
splay_tree_deallocate_fn deallocate;
- PTR GTY((skip (""))) allocate_data;
+ PTR GTY((skip)) allocate_data;
};
typedef struct splay_tree_s *splay_tree;