gcc/doc/gcc/extensions-to-the-c++-language/vague-linkage.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: vague linkage
   7
   8 .. _vague-linkage:
   9
  10 Vague Linkage
  11 *************
  12
  13 There are several constructs in C++ that require space in the object
  14 file but are not clearly tied to a single translation unit.  We say that
  15 these constructs have 'vague linkage'.  Typically such constructs are
  16 emitted wherever they are needed, though sometimes we can be more
  17 clever.
  18
  19 Inline Functions
  20   Inline functions are typically defined in a header file which can be
  21   included in many different compilations.  Hopefully they can usually be
  22   inlined, but sometimes an out-of-line copy is necessary, if the address
  23   of the function is taken or if inlining fails.  In general, we emit an
  24   out-of-line copy in all translation units where one is needed.  As an
  25   exception, we only emit inline virtual functions with the vtable, since
  26   it always requires a copy.
  27
  28   Local static variables and string constants used in an inline function
  29   are also considered to have vague linkage, since they must be shared
  30   between all inlined and out-of-line instances of the function.
  31
  32 VTables
  33   C++ virtual functions are implemented in most compilers using a lookup
  34   table, known as a vtable.  The vtable contains pointers to the virtual
  35   functions provided by a class, and each object of the class contains a
  36   pointer to its vtable (or vtables, in some multiple-inheritance
  37   situations).  If the class declares any non-inline, non-pure virtual
  38   functions, the first one is chosen as the 'key method' for the class,
  39   and the vtable is only emitted in the translation unit where the key
  40   method is defined.
  41
  42   .. note::
  43
  44     If the chosen key method is later defined as inline, the
  45     vtable is still emitted in every translation unit that defines it.
  46     Make sure that any inline virtuals are declared inline in the class
  47     body, even if they are not defined there.
  48
  49 :samp:`{type_info} objects`
  50   C++ requires information about types to be written out in order to
  51   implement :samp:`dynamic_cast`, :samp:`typeid` and exception handling.
  52   For polymorphic classes (classes with virtual functions), the :samp:`type_info`
  53   object is written out along with the vtable so that :samp:`dynamic_cast`
  54   can determine the dynamic type of a class object at run time.  For all
  55   other types, we write out the :samp:`type_info` object when it is used: when
  56   applying :samp:`typeid` to an expression, throwing an object, or
  57   referring to a type in a catch clause or exception specification.
  58
  59 Template Instantiations
  60   Most everything in this section also applies to template instantiations,
  61   but there are other options as well.
  62   See :ref:`template-instantiation`.
  63
  64 When used with GNU ld version 2.8 or later on an ELF system such as
  65 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
  66 these constructs will be discarded at link time.  This is known as
  67 COMDAT support.
  68
  69 On targets that don't support COMDAT, but do support weak symbols, GCC
  70 uses them.  This way one copy overrides all the others, but
  71 the unused copies still take up space in the executable.
  72
  73 For targets that do not support either COMDAT or weak symbols,
  74 most entities with vague linkage are emitted as local symbols to
  75 avoid duplicate definition errors from the linker.  This does not happen
  76 for local statics in inlines, however, as having multiple copies
  77 almost certainly breaks things.
  78
  79 See :ref:`c++-interface`, for
  80 another way to control placement of these constructs.