Mercurial > hg > CbC > CbC_gcc

comparison gcc/doc/gty.texi @ 67:f6334be47118

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
65:65488c3d617d 67:f6334be47118
1 @c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009 1 @c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009, 2010
2 @c Free Software Foundation, Inc. 2 @c Free Software Foundation, Inc.
3 @c This is part of the GCC manual. 3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi. 4 @c For copying conditions, see the file gcc.texi.
5 5
6 @node Type Information 6 @node Type Information
68 @menu 68 @menu
69 * GTY Options:: What goes inside a @code{GTY(())}. 69 * GTY Options:: What goes inside a @code{GTY(())}.
70 * GGC Roots:: Making global variables GGC roots. 70 * GGC Roots:: Making global variables GGC roots.
71 * Files:: How the generated files work. 71 * Files:: How the generated files work.
72 * Invoking the garbage collector:: How to invoke the garbage collector. 72 * Invoking the garbage collector:: How to invoke the garbage collector.
73 * Troubleshooting:: When something does not work as expected.
73 @end menu 74 @end menu
74 75
75 @node GTY Options 76 @node GTY Options
76 @section The Inside of a @code{GTY(())} 77 @section The Inside of a @code{GTY(())}
77 78
147 option is a fragment of C code that calculates the length. 148 option is a fragment of C code that calculates the length.
148 149
149 The second case is when a structure or a global variable contains a 150 The second case is when a structure or a global variable contains a
150 pointer to an array, like this: 151 pointer to an array, like this:
151 @smallexample 152 @smallexample
152 tree * 153 struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter;
153 GTY ((length ("%h.regno_pointer_align_length"))) regno_decl; 154 @end smallexample
154 @end smallexample 155 In this case, @code{iter} has been allocated by writing something like
155 In this case, @code{regno_decl} has been allocated by writing something like 156 @smallexample
156 @smallexample 157 x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse);
157 x->regno_decl = 158 @end smallexample
158 ggc_alloc (x->regno_pointer_align_length * sizeof (tree)); 159 and the @code{collapse} provides the length of the field.
159 @end smallexample
160 and the @code{length} provides the length of the field.
161 160
162 This second use of @code{length} also works on global variables, like: 161 This second use of @code{length} also works on global variables, like:
163 @verbatim 162 @verbatim
164 static GTY((length ("reg_base_value_size"))) 163 static GTY((length("reg_known_value_size"))) rtx *reg_known_value;
165 rtx *reg_base_value;
166 @end verbatim 164 @end verbatim
167 165
168 @findex skip 166 @findex skip
169 @item skip 167 @item skip
170 168
351 PCH cannot handle data structures that depend on the absolute values 349 PCH cannot handle data structures that depend on the absolute values
352 of pointers. @code{reorder} functions can be expensive. When 350 of pointers. @code{reorder} functions can be expensive. When
353 possible, it is better to depend on properties of the data, like an ID 351 possible, it is better to depend on properties of the data, like an ID
354 number or the hash of a string instead. 352 number or the hash of a string instead.
355 353
354 @findex variable_size
355 @item variable_size
356
357 The type machinery expects the types to be of constant size. When this
358 is not true, for example, with structs that have array fields or unions,
359 the type machinery cannot tell how many bytes need to be allocated at
360 each allocation. The @code{variable_size} is used to mark such types.
361 The type machinery then provides allocators that take a parameter
362 indicating an exact size of object being allocated. Note that the size
363 must be provided in bytes whereas the @code{length} option works with
364 array lengths in number of elements.
365
366 For example,
367 @smallexample
368 struct GTY((variable_size)) sorted_fields_type @{
369 int len;
370 tree GTY((length ("%h.len"))) elts[1];
371 @};
372 @end smallexample
373
374 Then the objects of @code{struct sorted_fields_type} are allocated in GC
375 memory as follows:
376 @smallexample
377 field_vec = ggc_alloc_sorted_fields_type (size);
378 @end smallexample
379
380 If @var{field_vec->elts} stores @var{n} elements, then @var{size}
381 could be calculated as follows:
382 @smallexample
383 size_t size = sizeof (struct sorted_fields_type) + n * sizeof (tree);
384 @end smallexample
385
356 @findex special 386 @findex special
357 @item special ("@var{name}") 387 @item special ("@var{name}")
358 388
359 The @code{special} option is used to mark types that have to be dealt 389 The @code{special} option is used to mark types that have to be dealt
360 with by special case machinery. The parameter is the name of the 390 with by special case machinery. The parameter is the name of the
464 494
465 The GCC garbage collector GGC is only invoked explicitly. In contrast 495 The GCC garbage collector GGC is only invoked explicitly. In contrast
466 with many other garbage collectors, it is not implicitly invoked by 496 with many other garbage collectors, it is not implicitly invoked by
467 allocation routines when a lot of memory has been consumed. So the 497 allocation routines when a lot of memory has been consumed. So the
468 only way to have GGC reclaim storage it to call the @code{ggc_collect} 498 only way to have GGC reclaim storage it to call the @code{ggc_collect}
469 function explicitly. This call is an expensive operation, as it may 499 function explicitly. This call is an expensive operation, as it may
470 have to scan the entire heap. Beware that local variables (on the GCC 500 have to scan the entire heap. Beware that local variables (on the GCC
471 call stack) are not followed by such an invocation (as many other 501 call stack) are not followed by such an invocation (as many other
472 garbage collectors do): you should reference all your data from static 502 garbage collectors do): you should reference all your data from static
473 or external @code{GTY}-ed variables, and it is advised to call 503 or external @code{GTY}-ed variables, and it is advised to call
474 @code{ggc_collect} with a shallow call stack. The GGC is an exact mark 504 @code{ggc_collect} with a shallow call stack. The GGC is an exact mark
475 and sweep garbage collector (so it does not scan the call stack for 505 and sweep garbage collector (so it does not scan the call stack for
476 pointers). In practice GCC passes don't often call @code{ggc_collect} 506 pointers). In practice GCC passes don't often call @code{ggc_collect}
477 themselves, because it is called by the pass manager between passes. 507 themselves, because it is called by the pass manager between passes.
508
509 At the time of the @code{ggc_collect} call all pointers in the GC-marked
510 structures must be valid or @code{NULL}. In practice this means that
511 there should not be uninitialized pointer fields in the structures even
512 if your code never reads or writes those fields at a particular
513 instance. One way to ensure this is to use cleared versions of
514 allocators unless all the fields are initialized manually immediately
515 after allocation.
516
517 @node Troubleshooting
518 @section Troubleshooting the garbage collector
519 @cindex garbage collector, troubleshooting
520
521 With the current garbage collector implementation, most issues should
522 show up as GCC compilation errors. Some of the most commonly
523 encountered issues are described below.
524
525 @itemize @bullet
526 @item Gengtype does not produce allocators for a @code{GTY}-marked type.
527 Gengtype checks if there is at least one possible path from GC roots to
528 at least one instance of each type before outputting allocators. If
529 there is no such path, the @code{GTY} markers will be ignored and no
530 allocators will be output. Solve this by making sure that there exists
531 at least one such path. If creating it is unfeasible or raises a ``code
532 smell'', consider if you really must use GC for allocating such type.
533
534 @item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and
535 similarly-named symbols. Check if your @file{foo_bar} source file has
536 @code{#include "gt-foo_bar.h"} as its very last line.
537
538 @end itemize