CbC/CbC_gcc: gcc/doc/gty.texi comparison

comparison gcc/doc/gty.texi @ 111:04ced10e8804

gcc 7

author	kono
date	Fri, 27 Oct 2017 22:46:09 +0900
parents	f6334be47118
children	84e7813d76e9

comparison

equal deleted inserted replaced

-:561a7518be6b
+:04ced10e8804
-@c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009, 2010
+@c Copyright (C) 2002-2017 Free Software Foundation, Inc.
-@c Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 @node Type Information
 @chapter Memory Management and Type Information
 GCC uses some fairly sophisticated memory management techniques, which
 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 complicated 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
+subset of C++ is interpreted and special markers are used to determine
-what parts of the source to look at.  All @code{struct} and
+what parts of the source to look at.  All @code{struct}, @code{union}
-@code{union} declarations that define data structures that are
+and @code{template} structure declarations that define data structures
-allocated under control of the garbage collector must be marked.  All
+that are allocated under control of the garbage collector must be
-global variables that hold pointers to garbage-collected memory must
+marked.  All global variables that hold pointers to garbage-collected
-also be marked.  Finally, all global variables that need to be saved
+memory must also be marked.  Finally, all global variables that need
-and restored by a precompiled header must be marked.  (The precompiled
+to be saved and restored by a precompiled header must be marked.  (The
-header mechanism can only save static variables if they're scalar.
+precompiled header mechanism can only save static variables if they're
-Complex data structures must be allocated in garbage-collected memory
+scalar. Complex data structures must be allocated in garbage-collected
-to be saved in a precompiled header.)
+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
 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.
+Since @code{gengtype}'s understanding of C++ is limited, there are
+several constructs and declarations that are not supported inside
+classes/structures marked for automatic GC code generation.  The
+following C++ constructs produce a @code{gengtype} error on
+structures/classes marked for automatic GC code generation:
+@itemize @bullet
+@item
+Type definitions inside classes/structures are not supported.
+@item
+Enumerations inside classes/structures are not supported.
+@end itemize
+If you have a class or structure using any of the above constructs,
+you need to mark that class as @code{GTY ((user))} and provide your
+own marking routines (see section @ref{User GC} for details).
+It is always valid to include function definitions inside classes.
+Those are always ignored by @code{gengtype}, as it only cares about
+data members.
 @menu
 * GTY Options::         What goes inside a @code{GTY(())}.
+* Inheritance and GTY:: Adding GTY to a class hierarchy.
+* User GC::		Adding user-provided GC marking routines.
 * 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
 @table @code
 @findex 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
+the length of an array of non-atomic objects.  The first case is when a
-variable-length array, like this:
+structure ends in a variable-length array, like this:
 @smallexample
 struct GTY(()) rtvec_def @{
 int num_elem;         /* @r{number of elements} */
 rtx GTY ((length ("%h.num_elem"))) elem[1];
 @};
 This second use of @code{length} also works on global variables, like:
 @verbatim
 static GTY((length("reg_known_value_size"))) rtx *reg_known_value;
 @end verbatim
+Note that the @code{length} option is only meant for use with arrays of
+non-atomic objects, that is, objects that contain pointers pointing to
+other GTY-managed objects.  For other GC-allocated arrays and strings
+you should use @code{atomic}.
 @findex skip
 @item skip
 If @code{skip} is applied to a field, the type machinery will ignore it.
 This is somewhat dangerous; the only safe use is in a union when one
 field really isn't ever used.
+@findex for_user
+@item for_user
+Use this to mark types that need to be marked by user gc routines, but are not
+refered to in a template argument.  So if you have some user gc type T1 and a
+non user gc type T2 you can give T2 the for_user option so that the marking
+functions for T1 can call non mangled functions to mark T2.
 @findex desc
 @findex tag
 @findex default
 @item desc ("@var{expression}")
 In this example, the value of BINDING_HAS_LEVEL_P when applied to a
 @code{struct tree_binding *} is presumed to be 0 or 1.  If 1, the type
 mechanism will treat the field @code{level} as being present and if 0,
 will treat the field @code{scope} as being present.
-@findex param_is
+The @code{desc} and @code{tag} options can also be used for inheritance
-@findex use_param
+to denote which subclass an instance is.  See @ref{Inheritance and GTY}
-@item param_is (@var{type})
+for more information.
-@itemx use_param
+@findex cache
-Sometimes it's convenient to define some data structure to work on
+@item cache
-generic pointers (that is, @code{PTR}) and then use it with a specific
-type.  @code{param_is} specifies the real type pointed to, and
+When the @code{cache} option is applied to a global variable gt_clear_cache is
-@code{use_param} says where in the generic data structure that type
+called on that variable between the mark and sweep phases of garbage
-should be put.
+collection.  The gt_clear_cache function is free to mark blocks as used, or to
+clear pointers in the variable.
-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
-static htab_t GTY ((param_is (union tree_node))) ict;
-@end smallexample
-@findex param@var{n}_is
-@findex use_param@var{n}
-@item param@var{n}_is (@var{type})
-@itemx use_param@var{n}
-In more complicated cases, the data structure might need to work on
-several different types, which might not necessarily all be pointers.
-For this, @code{param1_is} through @code{param9_is} may be used to
-specify the real type of a field identified by @code{use_param1} through
-@code{use_param9}.
-@findex use_params
-@item use_params
-When a structure contains another structure that is parameterized,
-there's no need to do anything special, the inner structure inherits the
-parameters of the outer one.  When a structure contains a pointer to a
-parameterized structure, the type machinery won't automatically detect
-this (it could, it just doesn't yet), so it's necessary to tell it that
-the pointed-to structure should use the same parameters as the outer
-structure.  This is done by marking the pointer with the
-@code{use_params} option.
 @findex deletable
 @item deletable
 @code{deletable}, when applied to a global variable, indicates that when
 garbage collection runs, there's no need to mark anything pointed to
 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 ("@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
-objects will never be freed, even if the last other reference to them
-goes away.  GGC has special handling to deal with this: if you use the
-@code{if_marked} option on a global hash table, GGC will call the
-routine whose name is the parameter to the option on each hash table
-entry.  If the routine returns nonzero, the hash table entry will
-be marked as usual.  If the routine returns zero, the hash table entry
-will be deleted.
-The routine @code{ggc_marked_p} can be used to determine if an element
-has been marked already; in fact, the usual case is to use
-@code{if_marked ("ggc_marked_p")}.
-@findex mark_hook
-@item mark_hook ("@var{hook-routine-name}")
-If provided for a structure or union type, the given
-@var{hook-routine-name} (between double-quotes) is the name of a
-routine called when the garbage collector has just marked the data as
-reachable. This routine should not change the data, or call any ggc
-routine. Its only argument is a pointer to the just marked (const)
-structure or union.
 @findex maybe_undef
 @item maybe_undef
 When applied to a field, @code{maybe_undef} indicates that it's OK if
 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 variable_size
+@findex atomic
-@item variable_size
+@item atomic
-The type machinery expects the types to be of constant size.  When this
+The @code{atomic} option can only be used with pointers.  It informs
-is not true, for example, with structs that have array fields or unions,
+the GC machinery that the memory that the pointer points to does not
-the type machinery cannot tell how many bytes need to be allocated at
+contain any pointers, and hence it should be treated by the GC and PCH
-each allocation.  The @code{variable_size} is used to mark such types.
+machinery as an ``atomic'' block of memory that does not need to be
-The type machinery then provides allocators that take a parameter
+examined when scanning memory for pointers.  In particular, the
-indicating an exact size of object being allocated.  Note that the size
+machinery will not scan that memory for pointers to mark them as
-must be provided in bytes whereas the @code{length} option works with
+reachable (when marking pointers for GC) or to relocate them (when
-array lengths in number of elements.
+writing a PCH file).
-For example,
+The @code{atomic} option differs from the @code{skip} option.
-@smallexample
+@code{atomic} keeps the memory under Garbage Collection, but makes the
-struct GTY((variable_size)) sorted_fields_type @{
+GC ignore the contents of the memory.  @code{skip} is more drastic in
-int len;
+that it causes the pointer and the memory to be completely ignored by
-tree GTY((length ("%h.len"))) elts[1];
+the Garbage Collector.  So, memory marked as @code{atomic} is
-@};
+automatically freed when no longer reachable, while memory marked as
-@end smallexample
+@code{skip} is not.
-Then the objects of @code{struct sorted_fields_type} are allocated in GC
+The @code{atomic} option must be used with great care, because all
-memory as follows:
+sorts of problem can occur if used incorrectly, that is, if the memory
-@smallexample
+the pointer points to does actually contain a pointer.
-field_vec = ggc_alloc_sorted_fields_type (size);
-@end smallexample
+Here is an example of how to use it:
+@smallexample
-If @var{field_vec->elts} stores @var{n} elements, then @var{size}
+struct GTY(()) my_struct @{
-could be calculated as follows:
+int number_of_elements;
-@smallexample
+unsigned int * GTY ((atomic)) elements;
-size_t size = sizeof (struct sorted_fields_type) + n * sizeof (tree);
+@};
 @end smallexample
+In this case, @code{elements} is a pointer under GC, and the memory it
+points to needs to be allocated using the Garbage Collector, and will
+be freed automatically by the Garbage Collector when it is no longer
+referenced.  But the memory that the pointer points to is an array of
+@code{unsigned int} elements, and the GC must not try to scan it to
+find pointers to mark or relocate, which is why it is marked with the
+@code{atomic} option.
+Note that, currently, global variables can not be marked with
+@code{atomic}; only fields of a struct can.  This is a known
+limitation.  It would be useful to be able to mark global pointers
+with @code{atomic} to make the PCH machinery aware of them so that
+they are saved and restored correctly to PCH files.
 @findex special
 @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.
+@findex user
+@item user
+The @code{user} option indicates that the code to mark structure
+fields is completely handled by user-provided routines.  See section
+@ref{User GC} for details on what functions need to be provided.
 @end table
+@node Inheritance and GTY
+@section Support for inheritance
+gengtype has some support for simple class hierarchies.  You can use
+this to have gengtype autogenerate marking routines, provided:
+@itemize @bullet
+@item
+There must be a concrete base class, with a discriminator expression
+that can be used to identify which subclass an instance is.
+@item
+Only single inheritance is used.
+@item
+None of the classes within the hierarchy are templates.
+@end itemize
+If your class hierarchy does not fit in this pattern, you must use
+@ref{User GC} instead.
+The base class and its discriminator must be identified using the ``desc''
+option.  Each concrete subclass must use the ``tag'' option to identify
+which value of the discriminator it corresponds to.
+Every class in the hierarchy must have a @code{GTY(())} marker, as
+gengtype will only attempt to parse classes that have such a marker
+@footnote{Classes lacking such a marker will not be identified as being
+part of the hierarchy, and so the marking routines will not handle them,
+leading to a assertion failure within the marking routines due to an
+unknown tag value (assuming that assertions are enabled).}.
+@smallexample
+class GTY((desc("%h.kind"), tag("0"))) example_base
+@{
+public:
+int kind;
+tree a;
+@};
+class GTY((tag("1"))) some_subclass : public example_base
+@{
+public:
+tree b;
+@};
+class GTY((tag("2"))) some_other_subclass : public example_base
+@{
+public:
+tree c;
+@};
+@end smallexample
+The generated marking routines for the above will contain a ``switch''
+on ``kind'', visiting all appropriate fields.  For example, if kind is
+2, it will cast to ``some_other_subclass'' and visit fields a, b, and c.
+@node User GC
+@section Support for user-provided GC marking routines
+@cindex user gc
+The garbage collector supports types for which no automatic marking
+code is generated.  For these types, the user is required to provide
+three functions: one to act as a marker for garbage collection, and
+two functions to act as marker and pointer walker for pre-compiled
+headers.
+Given a structure @code{struct GTY((user)) my_struct}, the following functions
+should be defined to mark @code{my_struct}:
+@smallexample
+void gt_ggc_mx (my_struct *p)
+@{
+/* This marks field 'fld'.  */
+gt_ggc_mx (p->fld);
+@}
+void gt_pch_nx (my_struct *p)
+@{
+/* This marks field 'fld'.  */
+gt_pch_nx (tp->fld);
+@}
+void gt_pch_nx (my_struct *p, gt_pointer_operator op, void *cookie)
+@{
+/* For every field 'fld', call the given pointer operator.  */
+op (&(tp->fld), cookie);
+@}
+@end smallexample
+In general, each marker @code{M} should call @code{M} for every
+pointer field in the structure.  Fields that are not allocated in GC
+or are not pointers must be ignored.
+For embedded lists (e.g., structures with a @code{next} or @code{prev}
+pointer), the marker must follow the chain and mark every element in
+it.
+Note that the rules for the pointer walker @code{gt_pch_nx (my_struct
+*, gt_pointer_operator, void *)} are slightly different.  In this
+case, the operation @code{op} must be applied to the @emph{address} of
+every pointer field.
+@subsection User-provided marking routines for template types
+When a template type @code{TP} is marked with @code{GTY}, all
+instances of that type are considered user-provided types.  This means
+that the individual instances of @code{TP} do not need to be marked
+with @code{GTY}.  The user needs to provide template functions to mark
+all the fields of the type.
+The following code snippets represent all the functions that need to
+be provided. Note that type @code{TP} may reference to more than one
+type. In these snippets, there is only one type @code{T}, but there
+could be more.
+@smallexample
+template<typename T>
+void gt_ggc_mx (TP<T> *tp)
+@{
+extern void gt_ggc_mx (T&);
+/* This marks field 'fld' of type 'T'.  */
+gt_ggc_mx (tp->fld);
+@}
+template<typename T>
+void gt_pch_nx (TP<T> *tp)
+@{
+extern void gt_pch_nx (T&);
+/* This marks field 'fld' of type 'T'.  */
+gt_pch_nx (tp->fld);
+@}
+template<typename T>
+void gt_pch_nx (TP<T *> *tp, gt_pointer_operator op, void *cookie)
+@{
+/* For every field 'fld' of 'tp' with type 'T *', call the given
+pointer operator.  */
+op (&(tp->fld), cookie);
+@}
+template<typename T>
+void gt_pch_nx (TP<T> *tp, gt_pointer_operator, void *cookie)
+@{
+extern void gt_pch_nx (T *, gt_pointer_operator, void *);
+/* For every field 'fld' of 'tp' with type 'T', call the pointer
+walker for all the fields of T.  */
+gt_pch_nx (&(tp->fld), op, cookie);
+@}
+@end smallexample
+Support for user-defined types is currently limited. The following
+restrictions apply:
+@enumerate
+@item Type @code{TP} and all the argument types @code{T} must be
+marked with @code{GTY}.
+@item Type @code{TP} can only have type names in its argument list.
+@item The pointer walker functions are different for @code{TP<T>} and
+@code{TP<T *>}. In the case of @code{TP<T>}, references to
+@code{T} must be handled by calling @code{gt_pch_nx} (which
+will, in turn, walk all the pointers inside fields of @code{T}).
+In the case of @code{TP<T *>}, references to @code{T *} must be
+handled by calling the @code{op} function on the address of the
+pointer (see the code snippets above).
+@end enumerate
 @node GGC Roots
 @section Marking Roots for the Garbage Collector
 @cindex roots, marking
 @cindex marking roots
 @code{GTFILES} variable in @file{Makefile.in}.
 @item
 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}.
+@file{config-lang.in}.
 Headers should appear before non-headers in this list.
 @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
 @findex ggc_collect
 The GCC garbage collector GGC is only invoked explicitly. In contrast
 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}
+only way to have GGC reclaim storage is 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
 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

Mercurial > hg > CbC > CbC_gcc

comparison gcc/doc/gty.texi @ 111:04ced10e8804