summaryrefslogtreecommitdiffstats
path: root/gnu/usr.bin/cc/doc/gxxint.texi
diff options
context:
space:
mode:
Diffstat (limited to 'gnu/usr.bin/cc/doc/gxxint.texi')
-rw-r--r--gnu/usr.bin/cc/doc/gxxint.texi1271
1 files changed, 1271 insertions, 0 deletions
diff --git a/gnu/usr.bin/cc/doc/gxxint.texi b/gnu/usr.bin/cc/doc/gxxint.texi
new file mode 100644
index 0000000..2441da1
--- /dev/null
+++ b/gnu/usr.bin/cc/doc/gxxint.texi
@@ -0,0 +1,1271 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename g++int.info
+@settitle G++ internals
+@setchapternewpage odd
+@c %**end of header
+
+@node Top, Limitations of g++, (dir), (dir)
+@chapter Internal Architecture of the Compiler
+
+This is meant to describe the C++ front-end for gcc in detail.
+Questions and comments to mrs@@cygnus.com.
+
+@menu
+* Limitations of g++::
+* Routines::
+* Implementation Specifics::
+* Glossary::
+* Macros::
+* Typical Behavior::
+* Coding Conventions::
+* Templates::
+* Access Control::
+* Error Reporting::
+* Parser::
+* Copying Objects::
+* Exception Handling::
+* Free Store::
+* Concept Index::
+@end menu
+
+@node Limitations of g++, Routines, Top, Top
+@section Limitations of g++
+
+@itemize @bullet
+@item
+Limitations on input source code: 240 nesting levels with the parser
+stacksize (YYSTACKSIZE) set to 500 (the default), and requires around
+16.4k swap space per nesting level. The parser needs about 2.09 *
+number of nesting levels worth of stackspace.
+
+@cindex pushdecl_class_level
+@item
+I suspect there are other uses of pushdecl_class_level that do not call
+set_identifier_type_value in tandem with the call to
+pushdecl_class_level. It would seem to be an omission.
+
+@cindex access checking
+@item
+Access checking is unimplemented for nested types.
+
+@cindex @code{volatile}
+@item
+@code{volatile} is not implemented in general.
+
+@cindex pointers to members
+@item
+Pointers to members are only minimally supported, and there are places
+where the grammar doesn't even properly accept them yet.
+
+@cindex multiple inheritance
+@item
+@code{this} will be wrong in virtual members functions defined in a
+virtual base class, when they are overridden in a derived class, when
+called via a non-left most object.
+
+An example would be:
+
+@example
+extern "C" int printf(const char*, ...);
+struct A @{ virtual void f() @{ @} @};
+struct B : virtual A @{ int b; B() : b(0) @{@} void f() @{ b++; @} @};
+struct C : B @{@};
+struct D : B @{@};
+struct E : C, D @{@};
+int main()
+@{
+ E e;
+ C& c = e; D& d = e;
+ c.f(); d.f();
+ printf ("C::b = %d, D::b = %d\n", e.C::b, e.D::b);
+ return 0;
+@}
+@end example
+
+This will print out 2, 0, instead of 1,1.
+
+@end itemize
+
+@node Routines, Implementation Specifics, Limitations of g++, Top
+@section Routines
+
+This section describes some of the routines used in the C++ front-end.
+
+@code{build_vtable} and @code{prepare_fresh_vtable} is used only within
+the @file{cp-class.c} file, and only in @code{finish_struct} and
+@code{modify_vtable_entries}.
+
+@code{build_vtable}, @code{prepare_fresh_vtable}, and
+@code{finish_struct} are the only routines that set @code{DECL_VPARENT}.
+
+@code{finish_struct} can steal the virtual function table from parents,
+this prohibits related_vslot from working. When finish_struct steals,
+we know that
+
+@example
+get_binfo (DECL_FIELD_CONTEXT (CLASSTYPE_VFIELD (t)), t, 0)
+@end example
+
+@noindent
+will get the related binfo.
+
+@code{layout_basetypes} does something with the VIRTUALS.
+
+Supposedly (according to Tiemann) most of the breadth first searching
+done, like in @code{get_base_distance} and in @code{get_binfo} was not
+because of any design decision. I have since found out the at least one
+part of the compiler needs the notion of depth first binfo searching, I
+am going to try and convert the whole thing, it should just work. The
+term left-most refers to the depth first left-most node. It uses
+@code{MAIN_VARIANT == type} as the condition to get left-most, because
+the things that have @code{BINFO_OFFSET}s of zero are shared and will
+have themselves as their own @code{MAIN_VARIANT}s. The non-shared right
+ones, are copies of the left-most one, hence if it is its own
+@code{MAIN_VARIENT}, we know it IS a left-most one, if it is not, it is
+a non-left-most one.
+
+@code{get_base_distance}'s path and distance matters in its use in:
+
+@itemize @bullet
+@item
+@code{prepare_fresh_vtable} (the code is probably wrong)
+@item
+@code{init_vfields} Depends upon distance probably in a safe way,
+build_offset_ref might use partial paths to do further lookups,
+hack_identifier is probably not properly checking access.
+
+@item
+@code{get_first_matching_virtual} probably should check for
+@code{get_base_distance} returning -2.
+
+@item
+@code{resolve_offset_ref} should be called in a more deterministic
+manner. Right now, it is called in some random contexts, like for
+arguments at @code{build_method_call} time, @code{default_conversion}
+time, @code{convert_arguments} time, @code{build_unary_op} time,
+@code{build_c_cast} time, @code{build_modify_expr} time,
+@code{convert_for_assignment} time, and
+@code{convert_for_initialization} time.
+
+But, there are still more contexts it needs to be called in, one was the
+ever simple:
+
+@example
+if (obj.*pmi != 7)
+ @dots{}
+@end example
+
+Seems that the problems were due to the fact that @code{TREE_TYPE} of
+the @code{OFFSET_REF} was not a @code{OFFSET_TYPE}, but rather the type
+of the referent (like @code{INTEGER_TYPE}). This problem was fixed by
+changing @code{default_conversion} to check @code{TREE_CODE (x)},
+instead of only checking @code{TREE_CODE (TREE_TYPE (x))} to see if it
+was @code{OFFSET_TYPE}.
+
+@end itemize
+
+@node Implementation Specifics, Glossary, Routines, Top
+@section Implementation Specifics
+
+@itemize @bullet
+@item Explicit Initialization
+
+The global list @code{current_member_init_list} contains the list of
+mem-initializers specified in a constructor declaration. For example:
+
+@example
+foo::foo() : a(1), b(2) @{@}
+@end example
+
+@noindent
+will initialize @samp{a} with 1 and @samp{b} with 2.
+@code{expand_member_init} places each initialization (a with 1) on the
+global list. Then, when the fndecl is being processed,
+@code{emit_base_init} runs down the list, initializing them. It used to
+be the case that g++ first ran down @code{current_member_init_list},
+then ran down the list of members initializing the ones that weren't
+explicitly initialized. Things were rewritten to perform the
+initializations in order of declaration in the class. So, for the above
+example, @samp{a} and @samp{b} will be initialized in the order that
+they were declared:
+
+@example
+class foo @{ public: int b; int a; foo (); @};
+@end example
+
+@noindent
+Thus, @samp{b} will be initialized with 2 first, then @samp{a} will be
+initialized with 1, regardless of how they're listed in the mem-initializer.
+
+@item Argument Matching
+
+In early 1993, the argument matching scheme in @sc{gnu} C++ changed
+significantly. The original code was completely replaced with a new
+method that will, hopefully, be easier to understand and make fixing
+specific cases much easier.
+
+The @samp{-fansi-overloading} option is used to enable the new code; at
+some point in the future, it will become the default behavior of the
+compiler.
+
+The file @file{cp-call.c} contains all of the new work, in the functions
+@code{rank_for_overload}, @code{compute_harshness},
+@code{compute_conversion_costs}, and @code{ideal_candidate}.
+
+Instead of using obscure numerical values, the quality of an argument
+match is now represented by clear, individual codes. The new data
+structure @code{struct harshness} (it used to be an @code{unsigned}
+number) contains:
+
+@enumerate a
+@item the @samp{code} field, to signify what was involved in matching two
+arguments;
+@item the @samp{distance} field, used in situations where inheritance
+decides which function should be called (one is ``closer'' than
+another);
+@item and the @samp{int_penalty} field, used by some codes as a tie-breaker.
+@end enumerate
+
+The @samp{code} field is a number with a given bit set for each type of
+code, OR'd together. The new codes are:
+
+@itemize @bullet
+@item @code{EVIL_CODE}
+The argument was not a permissible match.
+
+@item @code{CONST_CODE}
+Currently, this is only used by @code{compute_conversion_costs}, to
+distinguish when a non-@code{const} member function is called from a
+@code{const} member function.
+
+@item @code{ELLIPSIS_CODE}
+A match against an ellipsis @samp{...} is considered worse than all others.
+
+@item @code{USER_CODE}
+Used for a match involving a user-defined conversion.
+
+@item @code{STD_CODE}
+A match involving a standard conversion.
+
+@item @code{PROMO_CODE}
+A match involving an integral promotion. For these, the
+@code{int_penalty} field is used to handle the ARM's rule (XXX cite)
+that a smaller @code{unsigned} type should promote to a @code{int}, not
+to an @code{unsigned int}.
+
+@item @code{QUAL_CODE}
+Used to mark use of qualifiers like @code{const} and @code{volatile}.
+
+@item @code{TRIVIAL_CODE}
+Used for trivial conversions. The @samp{int_penalty} field is used by
+@code{convert_harshness} to communicate further penalty information back
+to @code{build_overload_call_real} when deciding which function should
+be call.
+@end itemize
+
+The functions @code{convert_to_aggr} and @code{build_method_call} use
+@code{compute_conversion_costs} to rate each argument's suitability for
+a given candidate function (that's how we get the list of candidates for
+@code{ideal_candidate}).
+
+@end itemize
+
+@node Glossary, Macros, Implementation Specifics, Top
+@section Glossary
+
+@table @r
+@item binfo
+The main data structure in the compiler used to represent the
+inheritance relationships between classes. The data in the binfo can be
+accessed by the BINFO_ accessor macros.
+
+@item vtable
+@itemx virtual function table
+
+The virtual function table holds information used in virtual function
+dispatching. In the compiler, they are usually referred to as vtables,
+or vtbls. The first index is not used in the normal way, I believe it
+is probably used for the virtual destructor.
+
+@item vfield
+
+vfields can be thought of as the base information needed to build
+vtables. For every vtable that exists for a class, there is a vfield.
+See also vtable and virtual function table pointer. When a type is used
+as a base class to another type, the virtual function table for the
+derived class can be based upon the vtable for the base class, just
+extended to include the additional virtual methods declared in the
+derived class. The virtual function table from a virtual base class is
+never reused in a derived class. @code{is_normal} depends upon this.
+
+@item virtual function table pointer
+
+These are @code{FIELD_DECL}s that are pointer types that point to
+vtables. See also vtable and vfield.
+@end table
+
+@node Macros, Typical Behavior, Glossary, Top
+@section Macros
+
+This section describes some of the macros used on trees. The list
+should be alphabetical. Eventually all macros should be documented
+here. There are some postscript drawings that can be used to better
+understnad from of the more complex data structures, contact Mike Stump
+(@code{mrs@@cygnus.com}) for information about them.
+
+@table @code
+@item BINFO_BASETYPES
+A vector of additional binfos for the types inherited by this basetype.
+The binfos are fully unshared (except for virtual bases, in which
+case the binfo structure is shared).
+
+ If this basetype describes type D as inherited in C,
+ and if the basetypes of D are E anf F,
+ then this vector contains binfos for inheritance of E and F by C.
+
+Has values of:
+
+ TREE_VECs
+
+
+@item BINFO_INHERITANCE_CHAIN
+Temporarily used to represent specific inheritances. It usually points
+to the binfo associated with the lesser derived type, but it can be
+reversed by reverse_path. For example:
+
+@example
+ Z ZbY least derived
+ |
+ Y YbX
+ |
+ X Xb most derived
+
+TYPE_BINFO (X) == Xb
+BINFO_INHERITANCE_CHAIN (Xb) == YbX
+BINFO_INHERITANCE_CHAIN (Yb) == ZbY
+BINFO_INHERITANCE_CHAIN (Zb) == 0
+@end example
+
+Not sure is the above is really true, get_base_distance has is point
+towards the most derived type, opposite from above.
+
+Set by build_vbase_path, recursive_bounded_basetype_p,
+get_base_distance, lookup_field, lookup_fnfields, and reverse_path.
+
+What things can this be used on:
+
+ TREE_VECs that are binfos
+
+
+@item BINFO_OFFSET
+The offset where this basetype appears in its containing type.
+BINFO_OFFSET slot holds the offset (in bytes) from the base of the
+complete object to the base of the part of the object that is allocated
+on behalf of this `type'. This is always 0 except when there is
+multiple inheritance.
+
+Used on TREE_VEC_ELTs of the binfos BINFO_BASETYPES (...) for example.
+
+
+@item BINFO_VIRTUALS
+A unique list of functions for the virtual function table. See also
+TYPE_BINFO_VIRTUALS.
+
+What things can this be used on:
+
+ TREE_VECs that are binfos
+
+
+@item BINFO_VTABLE
+Used to find the VAR_DECL that is the virtual function table associated
+with this binfo. See also TYPE_BINFO_VTABLE. To get the virtual
+function table pointer, see CLASSTYPE_VFIELD.
+
+What things can this be used on:
+
+ TREE_VECs that are binfos
+
+Has values of:
+
+ VAR_DECLs that are virtual function tables
+
+
+@item BLOCK_SUPERCONTEXT
+In the outermost scope of each function, it points to the FUNCTION_DECL
+node. It aids in better DWARF support of inline functions.
+
+
+@item CLASSTYPE_TAGS
+CLASSTYPE_TAGS is a linked (via TREE_CHAIN) list of member classes of a
+class. TREE_PURPOSE is the name, TREE_VALUE is the type (pushclass scans
+these and calls pushtag on them.)
+
+finish_struct scans these to produce TYPE_DECLs to add to the
+TYPE_FIELDS of the type.
+
+It is expected that name found in the TREE_PURPOSE slot is unique,
+resolve_scope_to_name is one such place that depends upon this
+uniqueness.
+
+
+@item CLASSTYPE_METHOD_VEC
+The following is true after finish_struct has been called (on the
+class?) but not before. Before finish_struct is called, things are
+different to some extent. Contains a TREE_VEC of methods of the class.
+The TREE_VEC_LENGTH is the number of differently named methods plus one
+for the 0th entry. The 0th entry is always allocated, and reserved for
+ctors and dtors. If there are none, TREE_VEC_ELT(N,0) == NULL_TREE.
+Each entry of the TREE_VEC is a FUNCTION_DECL. For each FUNCTION_DECL,
+there is a DECL_CHAIN slot. If the FUNCTION_DECL is the last one with a
+given name, the DECL_CHAIN slot is NULL_TREE. Otherwise it is the next
+method that has the same name (but a different signature). It would
+seem that it is not true that because the DECL_CHAIN slot is used in
+this way, we cannot call pushdecl to put the method in the global scope
+(cause that would overwrite the TREE_CHAIN slot), because they use
+different _CHAINs. finish_struct_methods setups up one version of the
+TREE_CHAIN slots on the FUNCTION_DECLs.
+
+friends are kept in TREE_LISTs, so that there's no need to use their
+TREE_CHAIN slot for anything.
+
+Has values of:
+
+ TREE_VECs
+
+
+@item CLASSTYPE_VFIELD
+Seems to be in the process of being renamed TYPE_VFIELD. Use on types
+to get the main virtual function table pointer. To get the virtual
+function table use BINFO_VTABLE (TYPE_BINFO ()).
+
+Has values of:
+
+ FIELD_DECLs that are virtual function table pointers
+
+What things can this be used on:
+
+ RECORD_TYPEs
+
+
+@item DECL_CLASS_CONTEXT
+Identifies the context that the _DECL was found in. For virtual function
+tables, it points to the type associated with the virtual function
+table. See also DECL_CONTEXT, DECL_FIELD_CONTEXT and DECL_FCONTEXT.
+
+The difference between this and DECL_CONTEXT, is that for virtuals
+functions like:
+
+@example
+struct A
+@{
+ virtual int f ();
+@};
+
+struct B : A
+@{
+ int f ();
+@};
+
+DECL_CONTEXT (A::f) == A
+DECL_CLASS_CONTEXT (A::f) == A
+
+DECL_CONTEXT (B::f) == A
+DECL_CLASS_CONTEXT (B::f) == B
+@end example
+
+Has values of:
+
+ RECORD_TYPEs, or UNION_TYPEs
+
+What things can this be used on:
+
+ TYPE_DECLs, _DECLs
+
+
+@item DECL_CONTEXT
+Identifies the context that the _DECL was found in. Can be used on
+virtual function tables to find the type associated with the virtual
+function table, but since they are FIELD_DECLs, DECL_FIELD_CONTEXT is a
+better access method. Internally the same as DECL_FIELD_CONTEXT, so
+don't us both. See also DECL_FIELD_CONTEXT, DECL_FCONTEXT and
+DECL_CLASS_CONTEXT.
+
+Has values of:
+
+ RECORD_TYPEs
+
+
+What things can this be used on:
+
+@display
+VAR_DECLs that are virtual function tables
+_DECLs
+@end display
+
+
+@item DECL_FIELD_CONTEXT
+Identifies the context that the FIELD_DECL was found in. Internally the
+same as DECL_CONTEXT, so don't us both. See also DECL_CONTEXT,
+DECL_FCONTEXT and DECL_CLASS_CONTEXT.
+
+Has values of:
+
+ RECORD_TYPEs
+
+What things can this be used on:
+
+@display
+FIELD_DECLs that are virtual function pointers
+FIELD_DECLs
+@end display
+
+
+@item DECL_NESTED_TYPENAME
+Holds the fully qualified type name. Example, Base::Derived.
+
+Has values of:
+
+ IDENTIFIER_NODEs
+
+What things can this be used on:
+
+ TYPE_DECLs
+
+
+@item DECL_NAME
+
+Has values of:
+
+@display
+0 for things that don't have names
+IDENTIFIER_NODEs for TYPE_DECLs
+@end display
+
+@item DECL_IGNORED_P
+A bit that can be set to inform the debug information output routines in
+the back-end that a certain _DECL node should be totally ignored.
+
+Used in cases where it is known that the debugging information will be
+output in another file, or where a sub-type is known not to be needed
+because the enclosing type is not needed.
+
+A compiler constructed virtual destructor in derived classes that do not
+define an exlicit destructor that was defined exlicit in a base class
+has this bit set as well. Also used on __FUNCTION__ and
+__PRETTY_FUNCTION__ to mark they are ``compiler generated.'' c-decl and
+c-lex.c both want DECL_IGNORED_P set for ``internally generated vars,''
+and ``user-invisible variable.''
+
+Functions built by the C++ front-end such as default destructors,
+virtual desctructors and default constructors want to be marked that
+they are compiler generated, but unsure why.
+
+Currently, it is used in an absolute way in the C++ front-end, as an
+optimization, to tell the debug information output routines to not
+generate debugging information that will be output by another separately
+compiled file.
+
+
+@item DECL_VIRTUAL_P
+A flag used on FIELD_DECLs and VAR_DECLs. (Documentation in tree.h is
+wrong.) Used in VAR_DECLs to indicate that the variable is a vtable.
+It is also used in FIELD_DECLs for vtable pointers.
+
+What things can this be used on:
+
+ FIELD_DECLs and VAR_DECLs
+
+
+@item DECL_VPARENT
+Used to point to the parent type of the vtable if there is one, else it
+is just the type associated with the vtable. Because of the sharing of
+virtual function tables that goes on, this slot is not very useful, and
+is in fact, not used in the compiler at all. It can be removed.
+
+What things can this be used on:
+
+ VAR_DECLs that are virtual function tables
+
+Has values of:
+
+ RECORD_TYPEs maybe UNION_TYPEs
+
+
+@item DECL_FCONTEXT
+Used to find the first baseclass in which this FIELD_DECL is defined.
+See also DECL_CONTEXT, DECL_FIELD_CONTEXT and DECL_CLASS_CONTEXT.
+
+How it is used:
+
+ Used when writing out debugging information about vfield and
+ vbase decls.
+
+What things can this be used on:
+
+ FIELD_DECLs that are virtual function pointers
+ FIELD_DECLs
+
+
+@item DECL_REFERENCE_SLOT
+Used to hold the initialize for the reference.
+
+What things can this be used on:
+
+ PARM_DECLs and VAR_DECLs that have a reference type
+
+
+@item DECL_VINDEX
+Used for FUNCTION_DECLs in two different ways. Before the structure
+containing the FUNCTION_DECL is laid out, DECL_VINDEX may point to a
+FUNCTION_DECL in a base class which is the FUNCTION_DECL which this
+FUNCTION_DECL will replace as a virtual function. When the class is
+laid out, this pointer is changed to an INTEGER_CST node which is
+suitable to find an index into the virtual function table. See
+get_vtable_entry as to how one can find the right index into the virtual
+function table. The first index 0, of a virtual function table it not
+used in the normal way, so the first real index is 1.
+
+DECL_VINDEX may be a TREE_LIST, that would seem to be a list of
+overridden FUNCTION_DECLs. add_virtual_function has code to deal with
+this when it uses the variable base_fndecl_list, but it would seem that
+somehow, it is possible for the TREE_LIST to pursist until method_call,
+and it should not.
+
+
+What things can this be used on:
+
+ FUNCTION_DECLs
+
+
+@item DECL_SOURCE_FILE
+Identifies what source file a particular declaration was found in.
+
+Has values of:
+
+ "<built-in>" on TYPE_DECLs to mean the typedef is built in
+
+
+@item DECL_SOURCE_LINE
+Identifies what source line number in the source file the declaration
+was found at.
+
+Has values of:
+
+@display
+0 for an undefined label
+
+0 for TYPE_DECLs that are internally generated
+
+0 for FUNCTION_DECLs for functions generated by the compiler
+ (not yet, but should be)
+
+0 for ``magic'' arguments to functions, that the user has no
+ control over
+@end display
+
+
+@item TREE_USED
+
+Has values of:
+
+ 0 for unused labels
+
+
+@item TREE_ADDRESSABLE
+A flag that is set for any type that has a constructor.
+
+
+@item TREE_COMPLEXITY
+They seem a kludge way to track recursion, poping, and pushing. They only
+appear in cp-decl.c and cp-decl2.c, so the are a good candidate for
+proper fixing, and removal.
+
+
+@item TREE_PRIVATE
+Set for FIELD_DECLs by finish_struct. But not uniformly set.
+
+The following routines do something with PRIVATE access:
+build_method_call, alter_access, finish_struct_methods,
+finish_struct, convert_to_aggr, CWriteLanguageDecl, CWriteLanguageType,
+CWriteUseObject, compute_access, lookup_field, dfs_pushdecl,
+GNU_xref_member, dbxout_type_fields, dbxout_type_method_1
+
+
+@item TREE_PROTECTED
+The following routines do something with PROTECTED access:
+build_method_call, alter_access, finish_struct, convert_to_aggr,
+CWriteLanguageDecl, CWriteLanguageType, CWriteUseObject,
+compute_access, lookup_field, GNU_xref_member, dbxout_type_fields,
+dbxout_type_method_1
+
+
+@item TYPE_BINFO
+Used to get the binfo for the type.
+
+Has values of:
+
+ TREE_VECs that are binfos
+
+What things can this be used on:
+
+ RECORD_TYPEs
+
+
+@item TYPE_BINFO_BASETYPES
+See also BINFO_BASETYPES.
+
+@item TYPE_BINFO_VIRTUALS
+A unique list of functions for the virtual function table. See also
+BINFO_VIRTUALS.
+
+What things can this be used on:
+
+ RECORD_TYPEs
+
+
+@item TYPE_BINFO_VTABLE
+Points to the virtual function table associated with the given type.
+See also BINFO_VTABLE.
+
+What things can this be used on:
+
+ RECORD_TYPEs
+
+Has values of:
+
+ VAR_DECLs that are virtual function tables
+
+
+@item TYPE_NAME
+Names the type.
+
+Has values of:
+
+@display
+0 for things that don't have names.
+should be IDENTIFIER_NODE for RECORD_TYPEs UNION_TYPEs and
+ ENUM_TYPEs.
+TYPE_DECL for RECORD_TYPEs, UNION_TYPEs and ENUM_TYPEs, but
+ shouldn't be.
+TYPE_DECL for typedefs, unsure why.
+@end display
+
+What things can one use this on:
+
+@display
+TYPE_DECLs
+RECORD_TYPEs
+UNION_TYPEs
+ENUM_TYPEs
+@end display
+
+History:
+
+ It currently points to the TYPE_DECL for RECORD_TYPEs,
+ UNION_TYPEs and ENUM_TYPEs, but it should be history soon.
+
+
+@item TYPE_METHODS
+Synonym for @code{CLASSTYPE_METHOD_VEC}. Chained together with
+@code{TREE_CHAIN}. @file{dbxout.c} uses this to get at the methods of a
+class.
+
+
+@item TYPE_DECL
+Used to represent typedefs, and used to represent bindings layers.
+
+Components:
+
+ DECL_NAME is the name of the typedef. For example, foo would
+ be found in the DECL_NAME slot when @code{typedef int foo;} is
+ seen.
+
+ DECL_SOURCE_LINE identifies what source line number in the
+ source file the declaration was found at. A value of 0
+ indicates that this TYPE_DECL is just an internal binding layer
+ marker, and does not correspond to a user suppiled typedef.
+
+ DECL_SOURCE_FILE
+
+@item TYPE_FIELDS
+A linked list (via @code{TREE_CHAIN}) of member types of a class. The
+list can contain @code{TYPE_DECL}s, but there can also be other things
+in the list apparently. See also @code{CLASSTYPE_TAGS}.
+
+
+@item TYPE_VIRTUAL_P
+A flag used on a @code{FIELD_DECL} or a @code{VAR_DECL}, indicates it is
+a virtual function table or a pointer to one. When used on a
+@code{FUNCTION_DECL}, indicates that it is a virtual function. When
+used on an @code{IDENTIFIER_NODE}, indicates that a function with this
+same name exists and has been declared virtual.
+
+When used on types, it indicates that the type has virtual functions, or
+is derived from one that does.
+
+Not sure if the above about virtual function tables is still true. See
+also info on @code{DECL_VIRTUAL_P}.
+
+What things can this be used on:
+
+ FIELD_DECLs, VAR_DECLs, FUNCTION_DECLs, IDENTIFIER_NODEs
+
+
+@item VF_BASETYPE_VALUE
+Get the associated type from the binfo that caused the given vfield to
+exist. This is the least derived class (the most parent class) that
+needed a virtual function table. It is probably the case that all uses
+of this field are misguided, but they need to be examined on a
+case-by-case basis. See history for more information on why the
+previous statement was made.
+
+Set at @code{finish_base_struct} time.
+
+What things can this be used on:
+
+ TREE_LISTs that are vfields
+
+History:
+
+ This field was used to determine if a virtual function table's
+ slot should be filled in with a certain virtual function, by
+ checking to see if the type returned by VF_BASETYPE_VALUE was a
+ parent of the context in which the old virtual function existed.
+ This incorrectly assumes that a given type _could_ not appear as
+ a parent twice in a given inheritance lattice. For single
+ inheritance, this would in fact work, because a type could not
+ possibly appear more than once in an inheritance lattice, but
+ with multiple inheritance, a type can appear more than once.
+
+
+@item VF_BINFO_VALUE
+Identifies the binfo that caused this vfield to exist. If this vfield
+is from the first direct base class that has a virtual function table,
+then VF_BINFO_VALUE is NULL_TREE, otherwise it will be the binfo of the
+direct base where the vfield came from. Can use @code{TREE_VIA_VIRTUAL}
+on result to find out if it is a virtual base class. Related to the
+binfo found by
+
+@example
+get_binfo (VF_BASETYPE_VALUE (vfield), t, 0)
+@end example
+
+@noindent
+where @samp{t} is the type that has the given vfield.
+
+@example
+get_binfo (VF_BASETYPE_VALUE (vfield), t, 0)
+@end example
+
+@noindent
+will return the binfo for the the given vfield.
+
+May or may not be set at @code{modify_vtable_entries} time. Set at
+@code{finish_base_struct} time.
+
+What things can this be used on:
+
+ TREE_LISTs that are vfields
+
+
+@item VF_DERIVED_VALUE
+Identifies the type of the most derived class of the vfield, excluding
+the the class this vfield is for.
+
+Set at @code{finish_base_struct} time.
+
+What things can this be used on:
+
+ TREE_LISTs that are vfields
+
+
+@item VF_NORMAL_VALUE
+Identifies the type of the most derived class of the vfield, including
+the class this vfield is for.
+
+Set at @code{finish_base_struct} time.
+
+What things can this be used on:
+
+ TREE_LISTs that are vfields
+
+
+@item WRITABLE_VTABLES
+This is a option that can be defined when building the compiler, that
+will cause the compiler to output vtables into the data segment so that
+the vtables maybe written. This is undefined by default, because
+normally the vtables should be unwritable. People that implement object
+I/O facilities may, or people that want to change the dynamic type of
+objects may want to have the vtables writable. Another way of achieving
+this would be to make a copy of the vtable into writable memory, but the
+drawback there is that that method only changes the type for one object.
+
+@end table
+
+@node Typical Behavior, Coding Conventions, Macros, Top
+@section Typical Behavior
+
+@cindex parse errors
+
+Whenever seemingly normal code fails with errors like
+@code{syntax error at `\@{'}, it's highly likely that grokdeclarator is
+returning a NULL_TREE for whatever reason.
+
+@node Coding Conventions, Templates, Typical Behavior, Top
+@section Coding Conventions
+
+It should never be that case that trees are modified in-place by the
+back-end, @emph{unless} it is guaranteed that the semantics are the same
+no matter how shared the tree structure is. @file{fold-const.c} still
+has some cases where this is not true, but rms hypothesizes that this
+will never be a problem.
+
+@node Templates, Access Control, Coding Conventions, Top
+@section Templates
+
+g++ uses the simple approach to instantiating templates: it blindly
+generates the code for each instantiation as needed. For class
+templates, g++ pushes the template parameters into the namespace for the
+duration of the instantiation; for function templates, it's a simple
+search and replace.
+
+This approach does not support any of the template definition-time error
+checking that is being bandied about by X3J16. It makes no attempt to deal
+with name binding in a consistent way.
+
+Instantiation of a class template is triggered by the use of a template
+class anywhere but in a straight declaration like @code{class A<int>}.
+This is wrong; in fact, it should not be triggered by typedefs or
+declarations of pointers. Now that explicit instantiation is supported,
+this misfeature is not necessary.
+
+Important functions:
+
+@table @code
+@item instantiate_class_template
+This function
+@end table
+
+@node Access Control, Error Reporting, Templates, Top
+@section Access Control
+The function compute_access returns one of three values:
+
+@table @code
+@item access_public
+means that the field can be accessed by the current lexical scope.
+
+@item access_protected
+means that the field cannot be accessed by the current lexical scope
+because it is protected.
+
+@item access_private
+means that the field cannot be accessed by the current lexical scope
+because it is private.
+@end table
+
+DECL_ACCESS is used for access declarations; alter_access creates a list
+of types and accesses for a given decl.
+
+Formerly, DECL_@{PUBLIC,PROTECTED,PRIVATE@} corresponded to the return
+codes of compute_access and were used as a cache for compute_access.
+Now they are not used at all.
+
+TREE_PROTECTED and TREE_PRIVATE are used to record the access levels
+granted by the containing class. BEWARE: TREE_PUBLIC means something
+completely unrelated to access control!
+
+@node Error Reporting, Parser, Access Control, Top
+@section Error Reporting
+
+The C++ front-end uses a call-back mechanism to allow functions to print
+out reasonable strings for types and functions without putting extra
+logic in the functions where errors are found. The interface is through
+the @code{cp_error} function (or @code{cp_warning}, etc.). The
+syntax is exactly like that of @code{error}, except that a few more
+conversions are supported:
+
+@itemize @bullet
+@item
+%C indicates a value of `enum tree_code'.
+@item
+%D indicates a *_DECL node.
+@item
+%E indicates a *_EXPR node.
+@item
+%L indicates a value of `enum languages'.
+@item
+%P indicates the name of a parameter (i.e. "this", "1", "2", ...)
+@item
+%T indicates a *_TYPE node.
+@item
+%O indicates the name of an operator (MODIFY_EXPR -> "operator =").
+
+@end itemize
+
+There is some overlap between these; for instance, any of the node
+options can be used for printing an identifier (though only @code{%D}
+tries to decipher function names).
+
+For a more verbose message (@code{class foo} as opposed to just @code{foo},
+including the return type for functions), use @code{%#c}.
+To have the line number on the error message indicate the line of the
+DECL, use @code{cp_error_at} and its ilk; to indicate which argument you want,
+use @code{%+D}, or it will default to the first.
+
+@node Parser, Copying Objects, Error Reporting, Top
+@section Parser
+
+Some comments on the parser:
+
+The @code{after_type_declarator} / @code{notype_declarator} hack is
+necessary in order to allow redeclarations of @code{TYPENAME}s, for
+instance
+
+@example
+typedef int foo;
+class A @{
+ char *foo;
+@};
+@end example
+
+In the above, the first @code{foo} is parsed as a @code{notype_declarator},
+and the second as a @code{after_type_declarator}.
+
+Ambiguities:
+
+There are currently four reduce/reduce ambiguities in the parser. They are:
+
+1) Between @code{template_parm} and
+@code{named_class_head_sans_basetype}, for the tokens @code{aggr
+identifier}. This situation occurs in code looking like
+
+@example
+template <class T> class A @{ @};
+@end example
+
+It is ambiguous whether @code{class T} should be parsed as the
+declaration of a template type parameter named @code{T} or an unnamed
+constant parameter of type @code{class T}. Section 14.6, paragraph 3 of
+the January '94 working paper states that the first interpretation is
+the correct one. This ambiguity results in two reduce/reduce conflicts.
+
+2) Between @code{primary} and @code{type_id} for code like @samp{int()}
+in places where both can be accepted, such as the argument to
+@code{sizeof}. Section 8.1 of the pre-San Diego working paper specifies
+that these ambiguous constructs will be interpreted as @code{typename}s.
+This ambiguity results in six reduce/reduce conflicts between
+@samp{absdcl} and @samp{functional_cast}.
+
+3) Between @code{functional_cast} and
+@code{complex_direct_notype_declarator}, for various token strings.
+This situation occurs in code looking like
+
+@example
+int (*a);
+@end example
+
+This code is ambiguous; it could be a declaration of the variable
+@samp{a} as a pointer to @samp{int}, or it could be a functional cast of
+@samp{*a} to @samp{int}. Section 6.8 specifies that the former
+interpretation is correct. This ambiguity results in 7 reduce/reduce
+conflicts. Another aspect of this ambiguity is code like 'int (x[2]);',
+which is resolved at the '[' and accounts for 6 reduce/reduce conflicts
+between @samp{direct_notype_declarator} and
+@samp{primary}/@samp{overqualified_id}. Finally, there are 4 r/r
+conflicts between @samp{expr_or_declarator} and @samp{primary} over code
+like 'int (a);', which could probably be resolved but would also
+probably be more trouble than it's worth. In all, this situation
+accounts for 17 conflicts. Ack!
+
+The second case above is responsible for the failure to parse 'LinppFile
+ppfile (String (argv[1]), &outs, argc, argv);' (from Rogue Wave
+Math.h++) as an object declaration, and must be fixed so that it does
+not resolve until later.
+
+4) Indirectly between @code{after_type_declarator} and @code{parm}, for
+type names. This occurs in (as one example) code like
+
+@example
+typedef int foo, bar;
+class A @{
+ foo (bar);
+@};
+@end example
+
+What is @code{bar} inside the class definition? We currently interpret
+it as a @code{parm}, as does Cfront, but IBM xlC interprets it as an
+@code{after_type_declarator}. I believe that xlC is correct, in light
+of 7.1p2, which says "The longest sequence of @i{decl-specifiers} that
+could possibly be a type name is taken as the @i{decl-specifier-seq} of
+a @i{declaration}." However, it seems clear that this rule must be
+violated in the case of constructors. This ambiguity accounts for 8
+conflicts.
+
+Unlike the others, this ambiguity is not recognized by the Working Paper.
+
+@node Copying Objects, Exception Handling, Parser, Top
+@section Copying Objects
+
+The generated copy assignment operator in g++ does not currently do the
+right thing for multiple inheritance involving virtual bases; it just
+calls the copy assignment operators for its direct bases. What it
+should probably do is:
+
+1) Split up the copy assignment operator for all classes that have
+vbases into "copy my vbases" and "copy everything else" parts. Or do
+the trickiness that the constructors do to ensure that vbases don't get
+initialized by intermediate bases.
+
+2) Wander through the class lattice, find all vbases for which no
+intermediate base has a user-defined copy assignment operator, and call
+their "copy everything else" routines. If not all of my vbases satisfy
+this criterion, warn, because this may be surprising behavior.
+
+3) Call the "copy everything else" routine for my direct bases.
+
+If we only have one direct base, we can just foist everything off onto
+them.
+
+This issue is currently under discussion in the core reflector
+(2/28/94).
+
+@node Exception Handling, Free Store, Copying Objects, Top
+@section Exception Handling
+
+Note, exception handling in g++ is still under development.
+
+This section describes the mapping of C++ exceptions in the C++
+front-end, into the back-end exception handling framework.
+
+The basic mechanism of exception handling in the back-end is
+unwind-protect a la elisp. This is a general, robust, and language
+independent representation for exceptions.
+
+The C++ front-end exceptions are mapping into the unwind-protect
+semantics by the C++ front-end. The mapping is describe below.
+
+Objects with RTTI support should use the RTTI information to do mapping
+and checking. Objects without RTTI, like int and const char *, have to
+use another means of matching. Currently we use the normal mangling used in
+building functions names. Int's are "i", const char * is PCc, etc...
+
+Unfortunately, the standard allows standard type conversions on throw
+parameters so they can match catch handlers. This means we need a
+mechanism to handle type conversion at run time, ICK. I read this part
+again, and it appears that we only have to be able to do a few of the
+conversions at run time, so we should be ok.
+
+In C++, all cleanups should be protected by exception regions. The
+region starts just after the reason why the cleanup is created has
+ended. For example, with an automatic variable, that has a constructor,
+it would be right after the constructor is run. The region ends just
+before the finalization is expanded. Since the backend may expand the
+cleanup multiple times along different paths, once for normal end of the
+region, once for non-local gotos, once for returns, etc, the backend
+must take special care to protect the finalization expansion, if the
+expansion is for any other reason than normal region end, and it is
+`inline' (it is inside the exception region). The backend can either
+choose to move them out of line, or it can created an exception region
+over the finalization to protect it, and in the handler associated with
+it, it would not run the finalization as it otherwise would have, but
+rather just rethrow to the outer handler, careful to skip the normal
+handler for the original region.
+
+In Ada, they will use the more runtime intensive approach of having
+fewer regions, but at the cost of additional work at run time, to keep a
+list of things that need cleanups. When a variable has finished
+construction, they add the cleanup to the list, when the come to the end
+of the lifetime of the variable, the run the list down. If the take a
+hit before the section finishes normally, they examine the list for
+actions to perform. I hope they add this logic into the back-end, as it
+would be nice to get that alternative approach in C++.
+
+On an rs6000, xlC stores exception objects on that stack, under the try
+block. When is unwinds down into a handler, the frame pointer is
+adjusted back to the normal value for the frame in which the handler
+resides, and the stack pointer is left unchanged from the time at which
+the object was throwed. This is so that there is always someplace for
+the exception object, and nothing can overwrite it, once we start
+throwing. The only bad part, is that the stack remains large.
+
+Flaws in g++'s exception handling. The stack pointer is restored from
+stack, we want to match rs6000, and propagate the stack pointer from
+time of throw, down, to the catch place.
+
+Only exact type matching of throw types works (references work also),
+catch variables cannot be used. Only works on a Sun sparc running SunOS
+4.1.x. Unwinding to outer catch clauses works. All temps and local
+variables are cleaned up in all unwinded scopes. Completed parts of
+partially constructed objects are not cleaned up. Don't expect
+exception handling to work right if you optimize, in fact the compiler
+will probably core dump. If two EH regions are the exact same size, the
+backend cannot tell which one is first. It punts by picking the last
+one, if they tie. This is usually right. We really should stick in a
+nop, if they are the same size.
+
+If we fall off the end of a series of catch blocks, we return to the
+flow of control in a normal fasion. But this is wrong, we should
+rethrow.
+
+When we invoke the copy constructor for an exception object because it
+is passed by value, and if we take a hit (exception) inside the copy
+constructor someplace, where do we go? I have tentatively choosen to
+not catch throws by the outer block at the same unwind level, if one
+exists, but rather to allow the frame to unwind into the next series of
+handlers, if any. If this is the wrong way to do it, we will need to
+protect the rest of the handler in some fashion. Maybe just changing
+the handler's handler to protect the whole series of handlers is the
+right way to go.
+
+The EH object is copied like it should be, if it is passed by value,
+otherwise we get a reference directly to it.
+
+EH objects make it through unwinding, but are subject to being
+overwritten as they are still past the top of stack. Don't throw
+automatic objects if this is a problem.
+
+Exceptions in catch handlers now go to outer block.
+
+@node Free Store, Concept Index, Exception Handling, Top
+@section Free Store
+
+operator new [] adds a magic cookie to the beginning of arrays for which
+the number of elements will be needed by operator delete []. These are
+arrays of objects with destructors and arrays of objects that define
+operator delete [] with the optional size_t argument. This cookie can
+be examined from a program as follows:
+
+@example
+typedef unsigned long size_t;
+extern "C" int printf (const char *, ...);
+
+size_t nelts (void *p)
+@{
+ struct cookie @{
+ size_t nelts __attribute__ ((aligned (sizeof (double))));
+ @};
+
+ cookie *cp = (cookie *)p;
+ --cp;
+
+ return cp->nelts;
+@}
+
+struct A @{
+ ~A() @{ @}
+@};
+
+main()
+@{
+ A *ap = new A[3];
+ printf ("%ld\n", nelts (ap));
+@}
+@end example
+
+@node Concept Index, , Free Store, Top
+@section Concept Index
+
+@printindex cp
+
+@bye
OpenPOWER on IntegriCloud