Return to g++int.texi CVS log

Up to [Apple XNU] / GNUtools / cc

Annotation of GNUtools/cc/g++int.texi, revision 1.1

1.1     ! root        1: \input texinfo  @c -*-texinfo-*-
        !             2: @c %**start of header 
        !             3: @setfilename g++int.info
        !             4: @settitle G++ internals
        !             5: @setchapternewpage odd
        !             6: @c %**end of header
        !             7:      
        !             8: @node Top, Limitations of g++, (dir), (dir)
        !             9: @chapter Internal Architecture of the Compiler
        !            10: 
        !            11: This is meant to describe the C++ frontend for gcc in detail.
        !            12: Questions and comments to mrs@@cygnus.com.
        !            13: 
        !            14: @menu
        !            15: * Limitations of g++::          
        !            16: * Routines::                    
        !            17: * Implementation Specifics::    
        !            18: * Glossary::                    
        !            19: * Macros::                      
        !            20: * Typical Behavior::            
        !            21: * Coding Conventions::          
        !            22: * Error Reporting::             
        !            23: * Concept Index::               
        !            24: @end menu
        !            25: 
        !            26: @node Limitations of g++, Routines, Top, Top
        !            27: @section Limitations of g++
        !            28: 
        !            29: @itemize @bullet
        !            30: @item
        !            31: Limitations on input source code: 240 nesting levels with the parser
        !            32: stacksize (YYSTACKSIZE) set to 500 (the default), and requires around
        !            33: 16.4k swap space per nesting level.  The parser needs about 2.09 *
        !            34: number of nesting levels worth of stackspace.
        !            35: 
        !            36: @cindex pushdecl_class_level
        !            37: @item
        !            38: I suspect there are other uses of pushdecl_class_level that do not call
        !            39: set_identifier_type_value in tandem with the call to
        !            40: pushdecl_class_level.  It would seem to be an omission.
        !            41: 
        !            42: @cindex delete, two argument
        !            43: @item
        !            44: For two argument delete, the second argument is always calculated by
        !            45: ``virtual_size ='' in the source.  It currently has a problem, in that
        !            46: object size is not calculated by the virtual destructor and passed back
        !            47: for the second parameter to delete.  Destructors need to return a value
        !            48: just like constructors.  ANSI C++ Jun 5 92 wp 12.5.6
        !            49: 
        !            50: The second argument is magically deleted in build_method_call, if it is
        !            51: not used.  It needs to be deleted for global operator delete also.
        !            52: 
        !            53: @cindex visibility checking
        !            54: @item
        !            55: Visibility checking in general is unimplemented, there are a few cases
        !            56: where it is implemented.  grok_enum_decls should be used in more places
        !            57: to do visibility checking, but this is only the tip of a bigger problem.
        !            58: 
        !            59: @cindex @code{volatile}
        !            60: @item
        !            61: @code{volatile} is not implemented in general.
        !            62: 
        !            63: @cindex pointers to members
        !            64: @item
        !            65: Pointers to members are only minimally supported, and there are places
        !            66: where the grammar doesn't even properly accept them yet.
        !            67: 
        !            68: @end itemize
        !            69: 
        !            70: @node Routines, Implementation Specifics, Limitations of g++, Top
        !            71: @section Routines
        !            72: 
        !            73: This section describes some of the routines used in the C++ front-end.
        !            74: 
        !            75: @code{build_vtable} and @code{prepare_fresh_vtable} is used only within
        !            76: the @file{cp-class.c} file, and only in @code{finish_struct} and
        !            77: @code{modify_vtable_entries}.
        !            78: 
        !            79: @code{build_vtable}, @code{prepare_fresh_vtable}, and
        !            80: @code{finish_struct} are the only routines that set @code{DECL_VPARENT}.
        !            81: 
        !            82: @code{finish_struct} can steal the virtual function table from parents,
        !            83: this prohibits related_vslot from working.  When finish_struct steals,
        !            84: we know that
        !            85: 
        !            86: @example
        !            87: get_binfo (DECL_FIELD_CONTEXT (CLASSTYPE_VFIELD (t)), t, 0)
        !            88: @end example
        !            89: 
        !            90: @noindent
        !            91: will get the related binfo.
        !            92: 
        !            93: @code{layout_basetypes} does something with the VIRTUALS.
        !            94: 
        !            95: Supposedly (according to Tiemann) most of the breadth first searching
        !            96: done, like in @code{get_base_distance} and in @code{get_binfo} was not
        !            97: because of any design decision.  I have since found out the at least one
        !            98: part of the compiler needs the notion of depth first binfo searching, I
        !            99: am going to try and convert the whole thing, it should just work.  The
        !           100: term left-most refers to the depth first left-most node.  It uses
        !           101: @code{MAIN_VARIANT == type} as the condition to get left-most, because
        !           102: the things that have @code{BINFO_OFFSET}s of zero are shared and will
        !           103: have themselves as their own @code{MAIN_VARIANT}s.  The non-shared right
        !           104: ones, are copies of the left-most one, hence if it is its own
        !           105: @code{MAIN_VARIENT}, we know it IS a left-most one, if it is not, it is
        !           106: a non-left-most one.
        !           107: 
        !           108: @code{get_base_distance}'s path and distance matters in its use in:
        !           109: 
        !           110: @itemize @bullet
        !           111: @item
        !           112: @code{prepare_fresh_vtable} (the code is probably wrong)
        !           113: @item
        !           114: @code{init_vfields} Depends upon distance probably in a safe way,
        !           115: build_offset_ref might use partial paths to do further lookups,
        !           116: hack_identifier is probably not properly checking visibility.
        !           117: 
        !           118: @item
        !           119: @code{get_first_matching_virtual} probably should check for
        !           120: @code{get_base_distance} returning -2.
        !           121: 
        !           122: @item
        !           123: @code{resolve_offset_ref} should be called in a more deterministic
        !           124: manner.  Right now, it is called in some random contexts, like for
        !           125: arguments at @code{build_method_call} time, @code{default_conversion}
        !           126: time, @code{convert_arguments} time, @code{build_unary_op} time,
        !           127: @code{build_c_cast} time, @code{build_modify_expr} time,
        !           128: @code{convert_for_assignment} time, and
        !           129: @code{convert_for_initialization} time.
        !           130: 
        !           131: But, there are still more contexts it needs to be called in, one was the
        !           132: ever simple:
        !           133: 
        !           134: @example
        !           135: if (obj.*pmi != 7)
        !           136:    @dots{}
        !           137: @end example
        !           138: 
        !           139: Seems that the problems were due to the fact that @code{TREE_TYPE} of
        !           140: the @code{OFFSET_REF} was not a @code{OFFSET_TYPE}, but rather the type
        !           141: of the referent (like @code{INTEGER_TYPE}).  This problem was fixed by
        !           142: changing @code{default_conversion} to check @code{TREE_CODE (x)},
        !           143: instead of only checking @code{TREE_CODE (TREE_TYPE (x))} to see if it
        !           144: was @code{OFFSET_TYPE}.
        !           145: 
        !           146: @end itemize
        !           147: 
        !           148: @node Implementation Specifics, Glossary, Routines, Top
        !           149: @section Implementation Specifics
        !           150: 
        !           151: @itemize @bullet
        !           152: @item Explicit Initialization
        !           153: 
        !           154: The global list @code{current_member_init_list} contains the list of
        !           155: mem-initializers specified in a constructor declaration.  For example:
        !           156: 
        !           157: @example
        !           158: foo::foo() : a(1), b(2) @{@}
        !           159: @end example
        !           160: 
        !           161: @noindent
        !           162: will initialize @samp{a} with 1 and @samp{b} with 2.
        !           163: @code{expand_member_init} places each initialization (a with 1) on the
        !           164: global list.  Then, when the fndecl is being processed,
        !           165: @code{emit_base_init} runs down the list, initializing them.  It used to
        !           166: be the case that g++ first ran down @code{current_member_init_list},
        !           167: then ran down the list of members initializing the ones that weren't
        !           168: explicitly initialized.  Things were rewritten to perform the
        !           169: initializations in order of declaration in the class.  So, for the above
        !           170: example, @samp{a} and @samp{b} will be initialized in the order that
        !           171: they were declared:
        !           172: 
        !           173: @example
        !           174: class foo @{ public: int b; int a; foo (); @};
        !           175: @end example
        !           176: 
        !           177: @noindent
        !           178: Thus, @samp{b} will be initialized with 2 first, then @samp{a} will be
        !           179: initialized with 1, regardless of how they're listed in the mem-initializer.
        !           180: 
        !           181: @item Argument Matching
        !           182: 
        !           183: In early 1993, the argument matching scheme in @sc{gnu} C++ changed
        !           184: significantly.  The original code was completely replaced with a new
        !           185: method that will, hopefully, be easier to understand and make fixing
        !           186: specific cases much easier.
        !           187: 
        !           188: The @samp{-fansi-overloading} option is used to enable the new code; at
        !           189: some point in the future, it will become the default behavior of the
        !           190: compiler.
        !           191: 
        !           192: The file @file{cp-call.c} contains all of the new work, in the functions
        !           193: @code{rank_for_overload}, @code{compute_harshness},
        !           194: @code{compute_conversion_costs}, and @code{ideal_candidate}.
        !           195: 
        !           196: Instead of using obscure numerical values, the quality of an argument
        !           197: match is now represented by clear, individual codes.  The new data
        !           198: structure @code{struct harshness} (it used to be an @code{unsigned}
        !           199: number) contains:
        !           200: 
        !           201: @enumerate a
        !           202: @item the @samp{code} field, to signify what was involved in matching two
        !           203: arguments;
        !           204: @item the @samp{distance} field, used in situations where inheritance
        !           205: decides which function should be called (one is ``closer'' than
        !           206: another);
        !           207: @item and the @samp{int_penalty} field, used by some codes as a tie-breaker.
        !           208: @end enumerate
        !           209: 
        !           210: The @samp{code} field is a number with a given bit set for each type of
        !           211: code, OR'd together.  The new codes are:
        !           212: 
        !           213: @itemize @bullet
        !           214: @item @code{EVIL_CODE}
        !           215: The argument was not a permissible match.
        !           216: 
        !           217: @item @code{CONST_CODE}
        !           218: Currently, this is only used by @code{compute_conversion_costs}, to
        !           219: distinguish when a non-@code{const} member function is called from a
        !           220: @code{const} member function.
        !           221: 
        !           222: @item @code{ELLIPSIS_CODE}
        !           223: A match against an ellipsis @samp{...} is considered worse than all others.
        !           224: 
        !           225: @item @code{USER_CODE}
        !           226: Used for a match involving a user-defined conversion.
        !           227: 
        !           228: @item @code{STD_CODE}
        !           229: A match involving a standard conversion.
        !           230: 
        !           231: @item @code{PROMO_CODE}
        !           232: A match involving an integral promotion.  For these, the
        !           233: @code{int_penalty} field is used to handle the ARM's rule (XXX cite)
        !           234: that a smaller @code{unsigned} type should promote to a @code{int}, not
        !           235: to an @code{unsigned int}.
        !           236: 
        !           237: @item @code{QUAL_CODE}
        !           238: Used to mark use of qualifiers like @code{const} and @code{volatile}.
        !           239: 
        !           240: @item @code{TRIVIAL_CODE}
        !           241: Used for trivial conversions.  The @samp{int_penalty} field is used by
        !           242: @code{convert_harshness} to communicate further penalty information back
        !           243: to @code{build_overload_call_real} when deciding which function should
        !           244: be call.
        !           245: @end itemize
        !           246: 
        !           247: The functions @code{convert_to_aggr} and @code{build_method_call} use
        !           248: @code{compute_conversion_costs} to rate each argument's suitability for
        !           249: a given candidate function (that's how we get the list of candidates for
        !           250: @code{ideal_candidate}).
        !           251: 
        !           252: @end itemize
        !           253: 
        !           254: @node Glossary, Macros, Implementation Specifics, Top
        !           255: @section Glossary
        !           256: 
        !           257: @table @r
        !           258: @item binfo
        !           259: The main data structure in the compiler used to represent the
        !           260: inheritance relationships between classes.  The data in the binfo can be
        !           261: accessed by the BINFO_ accessor macros.
        !           262: 
        !           263: @item vtable
        !           264: @itemx virtual function table
        !           265: 
        !           266: The virtual function table holds information used in virtual function
        !           267: dispatching.  In the compiler, they are usually referred to as vtables,
        !           268: or vtbls.  The first index is not used in the normal way, I believe it
        !           269: is probably used for the virtual destructor.
        !           270: 
        !           271: @item vfield
        !           272: 
        !           273: vfields can be thought of as the base information needed to build
        !           274: vtables.  For every vtable that exists for a class, there is a vfield.
        !           275: See also vtable and virtual function table pointer.  When a type is used
        !           276: as a base class to another type, the virtual function table for the
        !           277: derived class can be based upon the vtable for the base class, just
        !           278: extended to include the additional virtual methods declared in the
        !           279: derived class.
        !           280: 
        !           281: @item virtual function table pointer
        !           282: 
        !           283: These are @code{FIELD_DECL}s that are pointer types that point to
        !           284: vtables.  See also vtable and vfield.
        !           285: @end table
        !           286: 
        !           287: @node Macros, Typical Behavior, Glossary, Top
        !           288: @section Macros
        !           289: 
        !           290: This section describes some of the macros used on trees.  The list
        !           291: should be alphabetical.  Eventually all macros should be documented
        !           292: here.  There are some postscript drawings that can be used to better
        !           293: understnad from of the more complex data structures, contact Mike Stump
        !           294: (@code{mrs@@cygnus.com}) for information about them.
        !           295: 
        !           296: @table @code
        !           297: @item BINFO_BASETYPES
        !           298: A vector of additional binfos for the types inherited by this basetype.
        !           299: The binfos are fully unshared (except for virtual bases, in which
        !           300: case the binfo structure is shared).
        !           301: 
        !           302:    If this basetype describes type D as inherited in C,
        !           303:    and if the basetypes of D are E anf F,
        !           304:    then this vector contains binfos for inheritance of E and F by C.
        !           305: 
        !           306: Has values of:
        !           307: 
        !           308:        TREE_VECs
        !           309: 
        !           310: 
        !           311: @item BINFO_INHERITANCE_CHAIN
        !           312: Temporarily used to represent specific inheritances.  It usually points
        !           313: to the binfo associated with the lesser derived type, but it can be
        !           314: reversed by reverse_path.  For example:
        !           315: 
        !           316: @example
        !           317:        Z ZbY   least derived
        !           318:        |
        !           319:        Y YbX
        !           320:        |
        !           321:        X Xb    most derived
        !           322: 
        !           323: TYPE_BINFO (X) == Xb
        !           324: BINFO_INHERITANCE_CHAIN (Xb) == YbX
        !           325: BINFO_INHERITANCE_CHAIN (Yb) == ZbY
        !           326: BINFO_INHERITANCE_CHAIN (Zb) == 0
        !           327: @end example
        !           328: 
        !           329: Not sure is the above is really true, get_base_distance has is point
        !           330: towards the most derived type, opposite from above.
        !           331: 
        !           332: Set by build_vbase_path, recursive_bounded_basetype_p,
        !           333: get_base_distance, lookup_field, lookup_fnfields, and reverse_path.
        !           334: 
        !           335: What things can this be used on:
        !           336: 
        !           337:        TREE_VECs that are binfos
        !           338: 
        !           339: 
        !           340: @item BINFO_OFFSET
        !           341: The offset where this basetype appears in its containing type.
        !           342: BINFO_OFFSET slot holds the offset (in bytes) from the base of the
        !           343: complete object to the base of the part of the object that is allocated
        !           344: on behalf of this `type'.  This is always 0 except when there is
        !           345: multiple inheritance.
        !           346: 
        !           347: Used on TREE_VEC_ELTs of the binfos BINFO_BASETYPES (...) for example.
        !           348: 
        !           349: 
        !           350: @item BINFO_VIRTUALS
        !           351: A unique list of functions for the virtual function table.  See also
        !           352: TYPE_BINFO_VIRTUALS.
        !           353: 
        !           354: What things can this be used on:
        !           355: 
        !           356:        TREE_VECs that are binfos
        !           357: 
        !           358: 
        !           359: @item BINFO_VTABLE
        !           360: Used to find the VAR_DECL that is the virtual function table associated
        !           361: with this binfo.  See also TYPE_BINFO_VTABLE.  To get the virtual
        !           362: function table pointer, see CLASSTYPE_VFIELD.
        !           363: 
        !           364: What things can this be used on:
        !           365: 
        !           366:        TREE_VECs that are binfos
        !           367: 
        !           368: Has values of:
        !           369: 
        !           370:        VAR_DECLs that are virtual function tables
        !           371: 
        !           372: 
        !           373: @item BLOCK_SUPERCONTEXT
        !           374: In the outermost scope of each function, it points to the FUNCTION_DECL
        !           375: node.  It aids in better DWARF support of inline functions.
        !           376: 
        !           377: 
        !           378: @item CLASSTYPE_TAGS
        !           379: CLASSTYPE_TAGS is a linked (via TREE_CHAIN) list of member classes of a
        !           380: class. TREE_PURPOSE is the name, TREE_VALUE is the type (pushclass scans
        !           381: these and calls pushtag on them.)
        !           382: 
        !           383: finish_struct scans these to produce TYPE_DECLs to add to the
        !           384: TYPE_FIELDS of the type.
        !           385: 
        !           386: It is expected that name found in the TREE_PURPOSE slot is unique,
        !           387: resolve_scope_to_name is one such place that depends upon this
        !           388: uniqueness.
        !           389: 
        !           390: 
        !           391: @item CLASSTYPE_METHOD_VEC
        !           392: The following is true after finish_struct has been called (on the
        !           393: class?) but not before.  Before finish_struct is called, things are
        !           394: different to some extent.  Contains a TREE_VEC of methods of the class.
        !           395: The TREE_VEC_LENGTH is the number of differently named methods plus one
        !           396: for the 0th entry.  The 0th entry is always allocated, and reserved for
        !           397: ctors and dtors.  If there are none, TREE_VEC_ELT(N,0) == NULL_TREE.
        !           398: Each entry of the TREE_VEC is a FUNCTION_DECL.  For each FUNCTION_DECL,
        !           399: there is a DECL_CHAIN slot.  If the FUNCTION_DECL is the last one with a
        !           400: given name, the DECL_CHAIN slot is NULL_TREE.  Otherwise it is the next
        !           401: method that has the same name (but a different signature).  It would
        !           402: seem that it is not true that because the DECL_CHAIN slot is used in
        !           403: this way, we cannot call pushdecl to put the method in the global scope
        !           404: (cause that would overwrite the TREE_CHAIN slot), because they use
        !           405: different _CHAINs.  finish_struct_methods setups up one version of the
        !           406: TREE_CHAIN slots on the FUNCTION_DECLs.
        !           407: 
        !           408: friends are kept in TREE_LISTs, so that there's no need to use their
        !           409: TREE_CHAIN slot for anything.
        !           410: 
        !           411: Has values of:
        !           412: 
        !           413:        TREE_VECs
        !           414:        
        !           415: 
        !           416: @item CLASSTYPE_VFIELD
        !           417: Seems to be in the process of being renamed TYPE_VFIELD.  Use on types
        !           418: to get the main virtual function table pointer.  To get the virtual
        !           419: function table use BINFO_VTABLE (TYPE_BINFO ()).
        !           420: 
        !           421: Has values of:
        !           422: 
        !           423:        FIELD_DECLs that are virtual function table pointers
        !           424: 
        !           425: What things can this be used on:
        !           426: 
        !           427:        RECORD_TYPEs
        !           428: 
        !           429: 
        !           430: @item DECL_CLASS_CONTEXT
        !           431: Identifys the context that the _DECL was found in.  For virtual function
        !           432: tables, it points to the type associated with the virtual function
        !           433: table.  See also DECL_CONTEXT, DECL_FIELD_CONTEXT and DECL_FCONTEXT.
        !           434: 
        !           435: The difference between this and DECL_CONTEXT, is that for virtuals
        !           436: functions like:
        !           437: 
        !           438: @example
        !           439: struct A
        !           440: @{
        !           441:   virtual int f ();
        !           442: @};
        !           443: 
        !           444: struct B : A
        !           445: @{
        !           446:   int f ();
        !           447: @};
        !           448: 
        !           449: DECL_CONTEXT (A::f) == A
        !           450: DECL_CLASS_CONTEXT (A::f) == A
        !           451: 
        !           452: DECL_CONTEXT (B::f) == A
        !           453: DECL_CLASS_CONTEXT (B::f) == B
        !           454: @end example
        !           455: 
        !           456: Has values of:
        !           457: 
        !           458:        RECORD_TYPEs, or UNION_TYPEs
        !           459: 
        !           460: What things can this be used on:
        !           461: 
        !           462:        TYPE_DECLs, _DECLs
        !           463: 
        !           464: 
        !           465: @item DECL_CONTEXT
        !           466: Identifys the context that the _DECL was found in.  Can be used on
        !           467: virtual function tables to find the type associated with the virtual
        !           468: function table, but since they are FIELD_DECLs, DECL_FIELD_CONTEXT is a
        !           469: better access method.  Internally the same as DECL_FIELD_CONTEXT, so
        !           470: don't us both.  See also DECL_FIELD_CONTEXT, DECL_FCONTEXT and
        !           471: DECL_CLASS_CONTEXT.
        !           472: 
        !           473: Has values of:
        !           474: 
        !           475:        RECORD_TYPEs
        !           476: 
        !           477: 
        !           478: What things can this be used on:
        !           479: 
        !           480: @display
        !           481: VAR_DECLs that are virtual function tables
        !           482: _DECLs
        !           483: @end display
        !           484: 
        !           485: 
        !           486: @item DECL_FIELD_CONTEXT
        !           487: Identifys the context that the FIELD_DECL was found in.  Internally the
        !           488: same as DECL_CONTEXT, so don't us both.  See also DECL_CONTEXT,
        !           489: DECL_FCONTEXT and DECL_CLASS_CONTEXT.
        !           490: 
        !           491: Has values of:
        !           492: 
        !           493:        RECORD_TYPEs
        !           494: 
        !           495: What things can this be used on:
        !           496: 
        !           497: @display
        !           498: FIELD_DECLs that are virtual function pointers
        !           499: FIELD_DECLs
        !           500: @end display
        !           501: 
        !           502: 
        !           503: @item DECL_NESTED_TYPENAME
        !           504: Holds the fully qualified type name.  Example, Base::Derived.
        !           505: 
        !           506: Has values of:
        !           507: 
        !           508:        IDENTIFIER_NODEs
        !           509: 
        !           510: What things can this be used on:
        !           511: 
        !           512:        TYPE_DECLs
        !           513: 
        !           514: 
        !           515: @item DECL_NAME
        !           516: 
        !           517: Has values of:
        !           518: 
        !           519: @display
        !           520: 0 for things that don't have names
        !           521: IDENTIFIER_NODEs for TYPE_DECLs
        !           522: @end display
        !           523: 
        !           524: @item DECL_IGNORED_P
        !           525: A bit that can be set to inform the debug information output routines in
        !           526: the backend that a certain _DECL node should be totally ignored.
        !           527: 
        !           528: Used in cases where it is known that the debugging information will be
        !           529: output in another file, or where a sub-type is known not to be needed
        !           530: because the enclosing type is not needed.
        !           531: 
        !           532: A compiler constructed virtual destructor in derived classes that do not
        !           533: define an exlicit destructor that was defined exlicit in a base class
        !           534: has this bit set as well.  Also used on __FUNCTION__ and
        !           535: __PRETTY_FUNCTION__ to mark they are ``compiler generated.''  c-decl and
        !           536: c-lex.c both want DECL_IGNORED_P set for ``internally generated vars,''
        !           537: and ``user-invisible variable.''
        !           538: 
        !           539: Functions built by the C++ front-end such as default destructors,
        !           540: virtual desctructors and default constructors want to be marked that
        !           541: they are compiler generated, but unsure why.
        !           542: 
        !           543: Currently, it is used in an absolute way in the C++ front-end, as an
        !           544: optimization, to tell the debug information output routines to not
        !           545: generate debugging information that will be output by another separately
        !           546: compiled file.
        !           547: 
        !           548: 
        !           549: @item DECL_VIRTUAL_P
        !           550: A flag used on FIELD_DECLs and VAR_DECLs.  (Documentation in tree.h is
        !           551: wrong.)  Used in VAR_DECLs to indicate that the variable is a vtable.
        !           552: It is also used in FIELD_DECLs for vtable pointers.
        !           553: 
        !           554: What things can this be used on:
        !           555: 
        !           556:        FIELD_DECLs and VAR_DECLs
        !           557: 
        !           558: 
        !           559: @item DECL_VPARENT
        !           560: Used to point to the parent type of the vtable if there is one, else it
        !           561: is just the type associated with the vtable.  Because of the sharing of
        !           562: virtual function tables that goes on, this slot is not very useful, and
        !           563: is in fact, not used in the compiler at all.  It can be removed.
        !           564: 
        !           565: What things can this be used on:
        !           566: 
        !           567:        VAR_DECLs that are virtual function tables
        !           568: 
        !           569: Has values of:
        !           570: 
        !           571:        RECORD_TYPEs maybe UNION_TYPEs
        !           572: 
        !           573: 
        !           574: @item DECL_FCONTEXT
        !           575: Used to find the first baseclass in which this FIELD_DECL is defined.
        !           576: See also DECL_CONTEXT, DECL_FIELD_CONTEXT and DECL_CLASS_CONTEXT.
        !           577: 
        !           578: How it is used:
        !           579: 
        !           580:        Used when writing out debugging information about vfield and
        !           581:        vbase decls.
        !           582: 
        !           583: What things can this be used on:
        !           584: 
        !           585:        FIELD_DECLs that are virtual function pointers
        !           586:        FIELD_DECLs
        !           587: 
        !           588: 
        !           589: @item DECL_REFERENCE_SLOT
        !           590: Used to hold the initialize for the reference.
        !           591: 
        !           592: What things can this be used on:
        !           593: 
        !           594:        PARM_DECLs and VAR_DECLs that have a reference type
        !           595: 
        !           596: 
        !           597: @item DECL_VINDEX
        !           598: Used for FUNCTION_DECLs in two different ways.  Before the structure
        !           599: containing the FUNCTION_DECL is laid out, DECL_VINDEX may point to a
        !           600: FUNCTION_DECL in a base class which is the FUNCTION_DECL which this
        !           601: FUNCTION_DECL will replace as a virtual function.  When the class is
        !           602: laid out, this pointer is changed to an INTEGER_CST node which is
        !           603: suitable to find an index into the virtual function table.  See
        !           604: get_vtable_entry as to how one can find the right index into the virtual
        !           605: function table.  The first index 0, of a virtual function table it not
        !           606: used in the normal way, so the first real index is 1.
        !           607: 
        !           608: DECL_VINDEX may be a TREE_LIST, that would seem to be a list of
        !           609: overridden FUNCTION_DECLs.  add_virtual_function has code to deal with
        !           610: this when it uses the variable base_fndecl_list, but it would seem that
        !           611: somehow, it is possible for the TREE_LIST to pursist until method_call,
        !           612: and it should not.
        !           613: 
        !           614: 
        !           615: What things can this be used on:
        !           616: 
        !           617:        FUNCTION_DECLs
        !           618: 
        !           619: 
        !           620: @item DECL_SOURCE_FILE
        !           621: Identifies what source file a particular declaration was found in.
        !           622: 
        !           623: Has values of:
        !           624: 
        !           625:        "<built-in>" on TYPE_DECLs to mean the typedef is built in
        !           626: 
        !           627: 
        !           628: @item DECL_SOURCE_LINE
        !           629: Identifies what source line number in the source file the declaration
        !           630: was found at.
        !           631: 
        !           632: Has values of:
        !           633: 
        !           634: @display
        !           635: 0 for an undefined label
        !           636: 
        !           637: 0 for TYPE_DECLs that are internally generated
        !           638: 
        !           639: 0 for FUNCTION_DECLs for functions generated by the compiler
        !           640:        (not yet, but should be)
        !           641: 
        !           642: 0 for ``magic'' arguments to functions, that the user has no
        !           643:        control over
        !           644: @end display
        !           645: 
        !           646: 
        !           647: @item TREE_USED
        !           648: 
        !           649: Has values of:
        !           650: 
        !           651:        0 for unused labels
        !           652: 
        !           653: 
        !           654: @item TREE_ADDRESSABLE
        !           655: A flag that is set for any type that has a constructor.
        !           656: 
        !           657: 
        !           658: @item TREE_COMPLEXITY
        !           659: They seem a kludge way to track recursion, poping, and pushing.  They only
        !           660: appear in cp-decl.c and cp-decl2.c, so the are a good candidate for
        !           661: proper fixing, and removal.
        !           662: 
        !           663: 
        !           664: @item TREE_PRIVATE
        !           665: Set for FIELD_DECLs by finish_struct.  But not uniformly set.
        !           666: 
        !           667: The following routines do something with PRIVATE visibility:
        !           668: build_method_call, alter_visibility, finish_struct_methods,
        !           669: finish_struct, convert_to_aggr, CWriteLanguageDecl, CWriteLanguageType,
        !           670: CWriteUseObject, compute_visibility, lookup_field, dfs_pushdecl,
        !           671: GNU_xref_member, dbxout_type_fields, dbxout_type_method_1
        !           672: 
        !           673: 
        !           674: @item TREE_PROTECTED
        !           675: The following routines do something with PROTECTED visibility:
        !           676: build_method_call, alter_visibility, finish_struct, convert_to_aggr,
        !           677: CWriteLanguageDecl, CWriteLanguageType, CWriteUseObject,
        !           678: compute_visibility, lookup_field, GNU_xref_member, dbxout_type_fields,
        !           679: dbxout_type_method_1
        !           680: 
        !           681: 
        !           682: @item TYPE_BINFO
        !           683: Used to get the binfo for the type.
        !           684: 
        !           685: Has values of:
        !           686: 
        !           687:        TREE_VECs that are binfos
        !           688: 
        !           689: What things can this be used on:
        !           690: 
        !           691:        RECORD_TYPEs
        !           692: 
        !           693: 
        !           694: @item TYPE_BINFO_BASETYPES
        !           695: See also BINFO_BASETYPES.
        !           696: 
        !           697: @item TYPE_BINFO_VIRTUALS
        !           698: A unique list of functions for the virtual function table.  See also
        !           699: BINFO_VIRTUALS.
        !           700: 
        !           701: What things can this be used on:
        !           702: 
        !           703:        RECORD_TYPEs
        !           704: 
        !           705: 
        !           706: @item TYPE_BINFO_VTABLE
        !           707: Points to the virtual function table associated with the given type.
        !           708: See also BINFO_VTABLE.
        !           709: 
        !           710: What things can this be used on:
        !           711: 
        !           712:        RECORD_TYPEs
        !           713: 
        !           714: Has values of:
        !           715: 
        !           716:        VAR_DECLs that are virtual function tables
        !           717: 
        !           718: 
        !           719: @item TYPE_NAME
        !           720: Names the type.
        !           721: 
        !           722: Has values of:
        !           723: 
        !           724: @display
        !           725: 0 for things that don't have names.
        !           726: should be IDENTIFIER_NODE for RECORD_TYPEs UNION_TYPEs and 
        !           727:         ENUM_TYPEs.
        !           728: TYPE_DECL for RECORD_TYPEs, UNION_TYPEs and ENUM_TYPEs, but 
        !           729:         shouldn't be.
        !           730: TYPE_DECL for typedefs, unsure why.
        !           731: @end display
        !           732: 
        !           733: What things can one use this on:
        !           734: 
        !           735: @display
        !           736: TYPE_DECLs
        !           737: RECORD_TYPEs
        !           738: UNION_TYPEs
        !           739: ENUM_TYPEs
        !           740: @end display
        !           741: 
        !           742: History:
        !           743: 
        !           744:        It currently points to the TYPE_DECL for RECORD_TYPEs,
        !           745:        UNION_TYPEs and ENUM_TYPEs, but it should be history soon.
        !           746: 
        !           747: 
        !           748: @item TYPE_METHODS
        !           749: Synonym for @code{CLASSTYPE_METHOD_VEC}.  Chained together with
        !           750: @code{TREE_CHAIN}.  @file{dbxout.c} uses this to get at the methods of a
        !           751: class.
        !           752: 
        !           753: 
        !           754: @item TYPE_DECL
        !           755: Used to represent typedefs, and used to represent bindings layers.
        !           756: 
        !           757: Components:
        !           758: 
        !           759:        DECL_NAME is the name of the typedef.  For example, foo would
        !           760:        be found in the DECL_NAME slot when @code{typedef int foo;} is
        !           761:        seen.
        !           762: 
        !           763:        DECL_SOURCE_LINE identifies what source line number in the
        !           764:        source file the declaration was found at.  A value of 0
        !           765:        indicates that this TYPE_DECL is just an internal binding layer
        !           766:        marker, and does not correspond to a user suppiled typedef.
        !           767: 
        !           768:        DECL_SOURCE_FILE
        !           769: 
        !           770: @item TYPE_FIELDS
        !           771: A linked list (via @code{TREE_CHAIN}) of member types of a class.  The
        !           772: list can contain @code{TYPE_DECL}s, but there can also be other things
        !           773: in the list apparently.  See also @code{CLASSTYPE_TAGS}.
        !           774: 
        !           775: 
        !           776: @item TYPE_VIRTUAL_P
        !           777: A flag used on a @code{FIELD_DECL} or a @code{VAR_DECL}, indicates it is
        !           778: a virtual function table or a pointer to one.  When used on a
        !           779: @code{FUNCTION_DECL}, indicates that it is a virtual function.  When
        !           780: used on an @code{IDENTIFIER_NODE}, indicates that a function with this
        !           781: same name exists and has been declared virtual.
        !           782: 
        !           783: When used on types, it indicates that the type has virtual functions, or
        !           784: is derived from one that does.
        !           785: 
        !           786: Not sure if the above about virtual function tables is still true.  See
        !           787: also info on @code{DECL_VIRTUAL_P}.
        !           788: 
        !           789: What things can this be used on:
        !           790: 
        !           791:        FIELD_DECLs, VAR_DECLs, FUNCTION_DECLs, IDENTIFIER_NODEs
        !           792: 
        !           793: 
        !           794: @item VF_BASETYPE_VALUE
        !           795: Get the associated type from the binfo that caused the given vfield to
        !           796: exist.  This is the least derived class (the most parent class) that
        !           797: needed a virtual function table.  It is probably the case that all uses
        !           798: of this field are misguided, but they need to be examined on a
        !           799: case-by-case basis.  See history for more information on why the
        !           800: previous statement was made.
        !           801: 
        !           802: What things can this be used on:
        !           803: 
        !           804:        TREE_LISTs that are vfields
        !           805: 
        !           806: History:
        !           807: 
        !           808:        This field was used to determine if a virtual function table's
        !           809:        slot should be filled in with a certain virtual function, by
        !           810:        checking to see if the type returned by VF_BASETYPE_VALUE was a
        !           811:        parent of the context in which the old virtual function existed.
        !           812:        This incorrectly assumes that a given type _could_ not appear as
        !           813:        a parent twice in a given inheritance lattice.  For single
        !           814:        inheritance, this would in fact work, because a type could not
        !           815:        possibly appear more than once in an inheritance lattice, but
        !           816:        with multiple inheritance, a type can appear more than once.
        !           817: 
        !           818: 
        !           819: @item VF_BINFO_VALUE
        !           820: Identifies the binfo that caused this vfield to exist.  Can use
        !           821: @code{TREE_VIA_VIRTUAL} on result to find out if it is a virtual base
        !           822: class.  Related to the binfo found by
        !           823: 
        !           824: @example
        !           825: get_binfo (VF_BASETYPE_VALUE (vfield), t, 0)
        !           826: @end example
        !           827: 
        !           828: @noindent
        !           829: where @samp{t} is the type that has the given vfield.
        !           830: 
        !           831: @example
        !           832: get_binfo (VF_BASETYPE_VALUE (vfield), t, 0)
        !           833: @end example
        !           834: 
        !           835: @noindent
        !           836: will return the binfo for the the given vfield.
        !           837: 
        !           838: May or may not be set at @code{modify_vtable_entries} time.  Set at
        !           839: @code{finish_base_struct} time.
        !           840: 
        !           841: What things can this be used on:
        !           842: 
        !           843:        TREE_LISTs that are vfields
        !           844: 
        !           845: 
        !           846: @item VF_DERIVED_VALUE
        !           847: Identifies the type of the most derived class of the vfield, excluding
        !           848: the the class this vfield is for.
        !           849: 
        !           850: What things can this be used on:
        !           851: 
        !           852:        TREE_LISTs that are vfields
        !           853: 
        !           854: 
        !           855: @item VF_NORMAL_VALUE
        !           856: Identifies the type of the most derived class of the vfield, including
        !           857: the class this vfield is for.
        !           858: 
        !           859: What things can this be used on:
        !           860: 
        !           861:        TREE_LISTs that are vfields
        !           862: 
        !           863: 
        !           864: @item WRITABLE_VTABLES
        !           865: This is a option that can be defined when building the compiler, that
        !           866: will cause the compiler to output vtables into the data segment so that
        !           867: the vtables maybe written.  This is undefined by default, because
        !           868: normally the vtables should be unwritable.  People that implement object
        !           869: I/O facilities may, or people that want to change the dynamic type of
        !           870: objects may want to have the vtables writable.  Another way of achieving
        !           871: this would be to make a copy of the vtable into writable memory, but the
        !           872: drawback there is that that method only changes the type for one object.
        !           873: 
        !           874: @end table
        !           875: 
        !           876: @node Typical Behavior, Coding Conventions, Macros, Top
        !           877: @section Typical Behavior
        !           878: 
        !           879: @cindex parse errors
        !           880: 
        !           881: Whenever seemingly normal code fails with errors like
        !           882: @code{syntax error at `\@{'}, it's highly likely that grokdeclarator is
        !           883: returning a NULL_TREE for whatever reason.
        !           884: 
        !           885: @node Coding Conventions, Error Reporting, Typical Behavior, Top
        !           886: @section Coding Conventions
        !           887: 
        !           888: It should never be that case that trees are modified in-place by the
        !           889: back-end, @emph{unless} it is guaranteed that the semantics are the same
        !           890: no matter how shared the tree structure is.  @file{fold-const.c} still
        !           891: has some cases where this is not true, but rms hypothesizes that this
        !           892: will never be a problem.
        !           893: 
        !           894: @node Error Reporting, Concept Index, Coding Conventions, Top
        !           895: @section Error Reporting
        !           896: 
        !           897: The C++ frontend uses a call-back mechanism to allow functions to print
        !           898: out reasonable strings for types and functions without putting extra
        !           899: logic in the functions where errors are found.  The interface is through
        !           900: the @code{lang_error} function (or @code{lang_warning}, etc.).  The
        !           901: syntax is exactly like that of @code{error}, except that a few more
        !           902: conversions are supported:
        !           903: 
        !           904: @itemize @bullet
        !           905: @item
        !           906: %D indicates a *_DECL node
        !           907: @item
        !           908: %T indicates a *_TYPE node
        !           909: @item
        !           910: %E indicates a *_EXPR node (currently only used for default parameters
        !           911: in FUNCTION_DECLs)
        !           912: @end itemize
        !           913: 
        !           914: For a more verbose message (@code{class foo} as opposed to just @code{foo},
        !           915: including the return type for functions), use %#c.
        !           916: To have the line number on the error message indicate the line of the
        !           917: DECL, use @code{lang_error_at} and its ilk.
        !           918: 
        !           919: @node Concept Index,  , Error Reporting, Top
        !           920: @section Concept Index
        !           921: 
        !           922: @printindex cp
        !           923: 
        !           924: @bye

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.