[gc-improv] Update documentation

[Laurynas Biveinis <laurynas dot biveinis at gmail dot com>]

This documents the new GTY option variable_size and replaces GC
allocation in existing examples to use the typed allocation.

Tested by make info and make pdf, committed to gc-improv branch.

-- 
Laurynas


2010-03-19  Laurynas Biveinis  <laurynas.biveinis@gmail.com>

	* doc/gty.texi (GTY Options): Use typed GC allocation in
	examples.  Document variable_size option.

Index: gcc/doc/gty.texi
===================================================================
--- gcc/doc/gty.texi	(revision 157146)
+++ gcc/doc/gty.texi	(working copy)
@@ -149,20 +149,17 @@
 The second case is when a structure or a global variable contains a
 pointer to an array, like this:
 @smallexample
-tree *
-  GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
+struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter;
 @end smallexample
-In this case, @code{regno_decl} has been allocated by writing something like
+In this case, @code{iter} has been allocated by writing something like
 @smallexample
-  x->regno_decl =
-    ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
+  x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse);
 @end smallexample
-and the @code{length} provides the length of the field.
+and the @code{collapse} provides the length of the field.
 
 This second use of @code{length} also works on global variables, like:
 @verbatim
-  static GTY((length ("reg_base_value_size")))
-    rtx *reg_base_value;
+static GTY((length("reg_known_value_size"))) rtx *reg_known_value;
 @end verbatim
 
 @findex skip
@@ -353,6 +350,30 @@
 possible, it is better to depend on properties of the data, like an ID
 number or the hash of a string instead.
 
+@findex variable_size
+@item variable_size
+
+The type machinery expects the types to be of constant size.  When this
+is not true, for example, with structs that have array fields or unions,
+the type machinery cannot tell how many bytes need to be allocated at 
+each allocation.  The @code{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.  
+
+For example,
+@smallexample
+struct GTY((variable_size)) sorted_fields_type @{
+  int len;
+  tree GTY((length ("%h.len"))) elts[1];
+@};
+@end smallexample
+
+Then the objects of @code{struct sorted_fields_type} are allocated in GC 
+memory as follows:
+@smallexample
+  field_vec = ggc_alloc_sorted_fields_type (size);
+@end smallexample
+
 @findex special
 @item special ("@var{name}")