Mercurial > hg > CbC > CbC_gcc
diff gcc/doc/gty.texi @ 67:f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
author | nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp> |
---|---|
date | Tue, 22 Mar 2011 17:18:12 +0900 |
parents | 77e2b8dfacca |
children | 04ced10e8804 |
line wrap: on
line diff
--- a/gcc/doc/gty.texi Tue May 25 18:58:51 2010 +0900 +++ b/gcc/doc/gty.texi Tue Mar 22 17:18:12 2011 +0900 @@ -1,4 +1,4 @@ -@c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009 +@c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009, 2010 @c Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -70,6 +70,7 @@ * GGC Roots:: Making global variables GGC roots. * Files:: How the generated files work. * Invoking the garbage collector:: How to invoke the garbage collector. +* Troubleshooting:: When something does not work as expected. @end menu @node GTY Options @@ -149,20 +150,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 +351,38 @@ 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. Note that the size +must be provided in bytes whereas the @code{length} option works with +array lengths in number of elements. + +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 + +If @var{field_vec->elts} stores @var{n} elements, then @var{size} +could be calculated as follows: +@smallexample + size_t size = sizeof (struct sorted_fields_type) + n * sizeof (tree); +@end smallexample + @findex special @item special ("@var{name}") @@ -466,12 +496,43 @@ with many other garbage collectors, it is not implicitly invoked by 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} -function explicitly. This call is an expensive operation, as it may -have to scan the entire heap. Beware that local variables (on the GCC +function explicitly. This call is an expensive operation, as it may +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 garbage collectors do): you should reference all your data from static 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 -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. + +At the time of the @code{ggc_collect} call all pointers in the GC-marked +structures must be valid or @code{NULL}. In practice this means that +there should not be uninitialized pointer fields in the structures even +if your code never reads or writes those fields at a particular +instance. One way to ensure this is to use cleared versions of +allocators unless all the fields are initialized manually immediately +after allocation. + +@node Troubleshooting +@section Troubleshooting the garbage collector +@cindex garbage collector, troubleshooting + +With the current garbage collector implementation, most issues should +show up as GCC compilation errors. Some of the most commonly +encountered issues are described below. + +@itemize @bullet +@item Gengtype does not produce allocators for a @code{GTY}-marked type. +Gengtype checks if there is at least one possible path from GC roots to +at least one instance of each type before outputting allocators. If +there is no such path, the @code{GTY} markers will be ignored and no +allocators will be output. Solve this by making sure that there exists +at least one such path. If creating it is unfeasible or raises a ``code +smell'', consider if you really must use GC for allocating such type. + +@item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and +similarly-named symbols. Check if your @file{foo_bar} source file has +@code{#include "gt-foo_bar.h"} as its very last line. + +@end itemize