docs/DesignDocs/VisibilityMacros.rst

   1 ========================
   2 Symbol Visibility Macros
   3 ========================
   4
   5 .. contents::
   6    :local:
   7
   8 Overview
   9 ========
  10
  11 Libc++ uses various "visibility" macros in order to provide a stable ABI in
  12 both the library and the headers. These macros work by changing the
  13 visibility and inlining characteristics of the symbols they are applied to.
  14
  15 Visibility Macros
  16 =================
  17
  18 **_LIBCPP_HIDDEN**
  19   Mark a symbol as hidden so it will not be exported from shared libraries.
  20
  21 **_LIBCPP_FUNC_VIS**
  22   Mark a symbol as being exported by the libc++ library. This attribute must
  23   be applied to the declaration of all functions exported by the libc++ dylib.
  24
  25 **_LIBCPP_OVERRIDABLE_FUNC_VIS**
  26   Mark a symbol as being exported by the libc++ library, but allow it to be
  27   overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.
  28   This macro is applied to all `operator new` and `operator delete` overloads.
  29
  30   **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden
  31   locally, since `dllimport` indicates the symbol should be bound to a separate
  32   DLL. All `operator new` and `operator delete` overloads are required to be
  33   locally overridable, and therefore must not be marked `dllimport`. On Windows,
  34   this macro therefore expands to `__declspec(dllexport)` when building the
  35   library and has an empty definition otherwise.
  36
  37 **_LIBCPP_INLINE_VISIBILITY**
  38   Mark a function as hidden and force inlining whenever possible.
  39
  40 **_LIBCPP_ALWAYS_INLINE**
  41   A synonym for `_LIBCPP_INLINE_VISIBILITY`
  42
  43 **_LIBCPP_TYPE_VIS**
  44   Mark a type's typeinfo and vtable as having default visibility.
  45   `_LIBCPP_TYPE_VIS`. This macro has no effect on the visibility of the
  46   type's member functions. This attribute cannot be used on class templates.
  47
  48   **GCC Behavior**: GCC does not support Clang's `type_visibility(...)`
  49   attribute. With GCC the `visibility(...)` attribute is used and member
  50   functions are affected.
  51
  52 **_LIBCPP_TYPE_VIS_ONLY**
  53   The same as `_LIBCPP_TYPE_VIS` except that it may be applied to templates.
  54
  55   **Windows Behavior**: DLLs do not support dllimport/export on class templates.
  56   The macro has an empty definition on this platform.
  57
  58   Note: This macro should be renamed `_LIBCPP_TEMPLATE_TYPE_VIS`.
  59
  60 **_LIBCPP_ENUM_VIS**
  61   Mark the typeinfo of an enum as having default visibility. This attribute
  62   should be applied to all enum declarations.
  63
  64   **Windows Behavior**: DLLs do not support importing or exporting enumeration
  65   typeinfo. The macro has an empty definition on this platform.
  66
  67   **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even
  68   if `-fvisibility=hidden` is specified. Additionally applying a visibility
  69   attribute to an enum class results in a warning. The macro has an empty
  70   definition with GCC.
  71
  72 **_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**
  73   Mark the member functions, typeinfo, and vtable of the type named in
  74   a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library.
  75   This attribute must be specified on all extern class template declarations.
  76
  77   This macro is used to override the `_LIBCPP_TYPE_VIS_ONLY` attribute
  78   specified on the primary template and to export the member functions produced
  79   by the explicit instantiation in the dylib.
  80
  81   **GCC Behavior**: GCC ignores visibility attributes applied the type in
  82   extern template declarations and applying an attribute results in a warning.
  83   However since `_LIBCPP_TYPE_VIS_ONLY` is the same as `_LIBCPP_TYPE_VIS` the
  84   visibility is already correct. The macro has an empty definition with GCC.
  85
  86   **Windows Behavior**: `extern template` and `dllexport` are fundamentally
  87   incompatible *on a template class* on Windows; the former suppresses
  88   instantiation, while the latter forces it. Specifying both on the same
  89   declaration makes the template class be instantiated, which is not desirable
  90   inside headers. This macro therefore expands to `dllimport` outside of libc++
  91   but nothing inside of it (rather than expanding to `dllexport`); instead, the
  92   explicit instantiations themselves are marked as exported. Note that this
  93   applies *only* to extern template *classes*. Extern template *functions* obey
  94   regular import/export semantics, and applying `dllexport` directly to the
  95   extern template declaration is the correct thing to do for them.
  96
  97 **_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
  98   Mark the member functions, typeinfo, and vtable of an explicit instantiation
  99   of a class template as being exported by the libc++ library. This attribute
 100   must be specified on all template class explicit instantiations.
 101
 102   It is only necessary to mark the explicit instantiation itself (as opposed to
 103   the extern template declaration) as exported on Windows, as discussed above.
 104   On all other platforms, this macro has an empty definition.
 105
 106 **_LIBCPP_EXTERN_TEMPLATE_INLINE_VISIBILITY**
 107   Mark a member function of a class template as visible and always inline. This
 108   macro should only be applied to member functions of class templates that are
 109   externally instantiated. It is important that these symbols are not marked
 110   as hidden as that will prevent the dylib definition from being found.
 111
 112   This macro is used to maintain ABI compatibility for symbols that have been
 113   historically exported by the libc++ library but are now marked inline.
 114
 115 **_LIBCPP_EXCEPTION_ABI**
 116   Mark the member functions, typeinfo, and vtable of the type as being exported
 117   by the libc++ library. This macro must be applied to all *exception types*.
 118   Exception types should be defined directly in namespace `std` and not the
 119   versioning namespace. This allows throwing and catching some exception types
 120   between libc++ and libstdc++.
 121
 122 Links
 123 =====
 124
 125 * `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_
 126 * `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_
 127 * `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_