From 16c514027c01ecb36a9ca39b3bf3ef4334183738 Mon Sep 17 00:00:00 2001 From: dmalcolm Date: Tue, 29 Oct 2013 01:10:20 +0000 Subject: [PATCH] Add documentation about gengtype and inheritance * doc/gty.texi (GTY Options): Add note about inheritance to description of desc and tag. (Inheritance and GTY): New. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@204147 138bc75d-0d04-0410-961f-82ee72b054a4 --- gcc/ChangeLog | 6 ++++++ gcc/doc/gty.texi | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 3a391b0..ac7c86b 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,5 +1,11 @@ 2013-10-29 David Malcolm + * doc/gty.texi (GTY Options): Add note about inheritance to + description of desc and tag. + (Inheritance and GTY): New. + +2013-10-29 David Malcolm + * gengtype-parse.c (opts_have): Drop "static" so that we can use this from gengtype.c. * gengtype.c (set_gc_used_type): Mark any base class as used; diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi index 82e8e4f..090f6a6 100644 --- a/gcc/doc/gty.texi +++ b/gcc/doc/gty.texi @@ -87,6 +87,7 @@ 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. @@ -234,6 +235,10 @@ In this example, the value of BINDING_HAS_LEVEL_P when applied to a mechanism will treat the field @code{level} as being present and if 0, will treat the field @code{scope} as being present. +The @code{desc} and @code{tag} options can also be used for inheritance +to denote which subclass an instance is. See @ref{Inheritance and GTY} +for more information. + @findex param_is @findex use_param @item param_is (@var{type}) @@ -470,6 +475,53 @@ 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. + +@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 -- 2.7.4