add vague linkage node

From-SVN: r42389

diff --git a/gcc/extend.texi b/gcc/extend.texi
index 166f74458bd3f0499e31c924922077f7be032e16..0d96b25555b68c424a2f74678d55f7239e20ec57 100644 (file)
--- a/gcc/extend.texi
+++ b/gcc/extend.texi
@@ -3876,6 +3876,7 @@ Predefined Macros,cpp.info,The C Preprocessor}).
 * Min and Max::                C++ Minimum and maximum operators.
 * Volatiles::          What constitutes an access to a volatile object.
 * Restricted Pointers:: C99 restricted pointers and references.
+* Vague Linkage::       Where G++ puts inlines, vtables and such.
 * C++ Interface::       You can use a single C++ header file for both
                         declarations and definitions.
 * Template Instantiation:: Methods for ensuring that exactly one copy of
@@ -4063,6 +4064,83 @@ ignored in function definition matching. This means you only need to
 specify @code{__restrict__} in a function definition, rather than
 in a function prototype as well.
 
+@node Vague Linkage
+@section Vague Linkage
+@cindex vague linkage
+
+There are several constructs in C++ which require space in the object
+file but are not clearly tied to a single translation unit.  We say that
+these constructs have ``vague linkage''.  Typically such constructs are
+emitted wherever they are needed, though sometimes we can be more
+clever.
+
+@table @asis
+@item Inline Functions
+Inline functions are typically defined in a header file which can be
+included in many different compilations.  Hopefully they can usually be
+inlined, but sometimes an out-of-line copy is necessary, if the address
+of the function is taken or if inlining fails.  In general, we emit an
+out-of-line copy in all translation units where one is needed.  As an
+exception, we only emit inline virtual functions with the vtable, since
+it will always require a copy.
+
+Local static variables and string constants used in an inline function
+are also considered to have vague linkage, since they must be shared
+between all inlined and out-of-line instances of the function.
+
+@item VTables
+@cindex vtable
+C++ virtual functions are implemented in most compilers using a lookup
+table, known as a vtable.  The vtable contains pointers to the virtual
+functions provided by a class, and each object of the class contains a
+pointer to its vtable (or vtables, in some multiple-inheritance
+situations).  If the class declares any non-inline, non-pure virtual
+functions, the first one is chosen as the ``key method'' for the class,
+and the vtable is only emitted in the translation unit where the key
+method is defined.
+
+@emph{Note:} If the chosen key method is later defined as inline, the
+vtable will still be emitted in every translation unit which defines it.
+Make sure that any inline virtuals are declared inline in the class
+body, even if they are not defined there.
+
+@item type_info objects
+@cindex type_info
+@cindex RTTI
+C++ requires information about types to be written out in order to
+implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
+For polymorphic classes (classes with virtual functions), the type_info
+object is written out along with the vtable so that @samp{dynamic_cast}
+can determine the dynamic type of a class object at runtime.  For all
+other types, we write out the type_info object when it is used: when
+applying @samp{typeid} to an expression, throwing an object, or
+referring to a type in a catch clause or exception specification.
+
+@item Template Instantiations
+Most everything in this section also applies to template instantiations,
+but there are other options as well.
+@xref{Template Instantiation,,Where's the Template?}.
+
+@end table
+
+When used with GNU ld version 2.8 or later on an ELF system such as
+Linux/GNU or Solaris 2, or on Microsoft Windows, duplicate copies of
+these constructs will be discarded at link time.  This is known as
+COMDAT support.
+
+On targets that don't support COMDAT, but do support weak symbols, GCC
+will use them.  This way one copy will override all the others, but
+the unused copies will still take up space in the executable.
+
+For targets which do not support either COMDAT or weak symbols,
+most entities with vague linkage will be emitted as local symbols to
+avoid duplicate definition errors from the linker.  This will not happen
+for local statics in inlines, however, as having multiple copies will
+almost certainly break things.
+
+@xref{C++ Interface,,Declarations and Definitions in One Header}, for
+another way to control placement of these constructs.
+
 @node C++ Interface
 @section Declarations and Definitions in One Header
 
@@ -4426,23 +4504,6 @@ Some_Class  B  __attribute__ ((init_priority (543)));
 Note that the particular values of @var{priority} do not matter; only their
 relative ordering.
 
-
-@item com_interface
-@cindex com_interface attribute
-
-@c This is based on:  1) grepping the code,
-@c 2) http://gcc.gnu.org/ml/gcc-bugs/1999-08n/msg01212.html
-@c 3) http://gcc.gnu.org/ml/gcc-bugs/1999-08n/msg01215.html
-@c and 4) a lot of guesswork.  You can tell I don't use COM.  -pme 21Dec00
-
-This type attribute takes no parameters, and marks a class or struct as an
-interface for communication via COM; the class will support the COM ABI
-rather than the full C++ ABI.  Currently this means that RTTI is not possible
-with the resulting class heirarchy.  The virtual pointer table will be
-changed to be COM-compliant.  Also, all classes and structs derived from one
-marked with this attribute are implicitly marked with the same attribute;
-thus, only the base class in a COM hierarchy needs @code{com_interface}.
-
 @item java_interface
 @cindex java_interface attribute