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_EXPORTED_FROM_ABI**
  26   Mark a symbol as being exported by the libc++ library. This attribute may
  27   only be applied to objects defined in the libc++ runtime library. On Windows,
  28   this macro applies `dllimport`/`dllexport` to the symbol, and on other
  29   platforms it gives the symbol default visibility.
  30
  31 **_LIBCPP_OVERRIDABLE_FUNC_VIS**
  32   Mark a symbol as being exported by the libc++ library, but allow it to be
  33   overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.
  34   This macro is applied to all `operator new` and `operator delete` overloads.
  35
  36   **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden
  37   locally, since `dllimport` indicates the symbol should be bound to a separate
  38   DLL. All `operator new` and `operator delete` overloads are required to be
  39   locally overridable, and therefore must not be marked `dllimport`. On Windows,
  40   this macro therefore expands to `__declspec(dllexport)` when building the
  41   library and has an empty definition otherwise.
  42
  43 **_LIBCPP_HIDE_FROM_ABI**
  44   Mark a function as not being part of the ABI of any final linked image that
  45   uses it.
  46
  47 **_LIBCPP_HIDE_FROM_ABI_AFTER_V1**
  48   Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`)
  49   when libc++ is built with an ABI version after ABI v1. This macro is used to
  50   maintain ABI compatibility for symbols that have been historically exported
  51   by libc++ in v1 of the ABI, but that we don't want to export in the future.
  52
  53   This macro works as follows. When we build libc++, we either hide the symbol
  54   from the ABI (if the symbol is not part of the ABI in the version we're
  55   building), or we leave it included. From user code (i.e. when we're not
  56   building libc++), the macro always marks symbols as internal so that programs
  57   built using new libc++ headers stop relying on symbols that are removed from
  58   the ABI in a future version. Each time we release a new stable version of the
  59   ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can
  60   use it to start removing symbols from the ABI after that stable version.
  61
  62 **_LIBCPP_HIDE_FROM_ABI_PER_TU**
  63   This macro controls whether symbols hidden from the ABI with `_LIBCPP_HIDE_FROM_ABI`
  64   are local to each translation unit in addition to being local to each final
  65   linked image. This macro is defined to either 0 or 1. When it is defined to
  66   1, translation units compiled with different versions of libc++ can be linked
  67   together, since all non ABI-facing functions are local to each translation unit.
  68   This allows static archives built with different versions of libc++ to be linked
  69   together. This also means that functions marked with `_LIBCPP_HIDE_FROM_ABI`
  70   are not guaranteed to have the same address across translation unit boundaries.
  71
  72   When the macro is defined to 0, there is no guarantee that translation units
  73   compiled with different versions of libc++ can interoperate. However, this
  74   leads to code size improvements, since non ABI-facing functions can be
  75   deduplicated across translation unit boundaries.
  76
  77   This macro can be defined by users to control the behavior they want from
  78   libc++. The default value of this macro (0 or 1) is controlled by whether
  79   `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined, which is intended to
  80   be used by vendors only (see below).
  81
  82 **_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT**
  83   This macro controls the default value for `_LIBCPP_HIDE_FROM_ABI_PER_TU`.
  84   When the macro is defined, per TU ABI insulation is enabled by default, and
  85   `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 1 unless overridden by users.
  86   Otherwise, per TU ABI insulation is disabled by default, and
  87   `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 0 unless overridden by users.
  88
  89   This macro is intended for vendors to control whether they want to ship
  90   libc++ with per TU ABI insulation enabled by default. Users can always
  91   control the behavior they want by defining `_LIBCPP_HIDE_FROM_ABI_PER_TU`
  92   appropriately.
  93
  94   By default, this macro is not defined, which means that per TU ABI insulation
  95   is not provided unless explicitly overridden by users.
  96
  97 **_LIBCPP_TYPE_VIS**
  98   Mark a type's typeinfo, vtable and members as having default visibility.
  99   This attribute cannot be used on class templates.
 100
 101 **_LIBCPP_TEMPLATE_VIS**
 102   Mark a type's typeinfo and vtable as having default visibility.
 103   This macro has no effect on the visibility of the type's member functions.
 104
 105   **GCC Behavior**: GCC does not support Clang's `type_visibility(...)`
 106   attribute. With GCC the `visibility(...)` attribute is used and member
 107   functions are affected.
 108
 109   **Windows Behavior**: DLLs do not support dllimport/export on class templates.
 110   The macro has an empty definition on this platform.
 111
 112
 113 **_LIBCPP_ENUM_VIS**
 114   Mark the typeinfo of an enum as having default visibility. This attribute
 115   should be applied to all enum declarations.
 116
 117   **Windows Behavior**: DLLs do not support importing or exporting enumeration
 118   typeinfo. The macro has an empty definition on this platform.
 119
 120   **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even
 121   if `-fvisibility=hidden` is specified. Additionally applying a visibility
 122   attribute to an enum class results in a warning. The macro has an empty
 123   definition with GCC.
 124
 125 **_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**
 126   Mark the member functions, typeinfo, and vtable of the type named in
 127   a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library.
 128   This attribute must be specified on all extern class template declarations.
 129
 130   This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute
 131   specified on the primary template and to export the member functions produced
 132   by the explicit instantiation in the dylib.
 133
 134   **GCC Behavior**: GCC ignores visibility attributes applied the type in
 135   extern template declarations and applying an attribute results in a warning.
 136   However since `_LIBCPP_TEMPLATE_VIS` is the same as
 137   `__attribute__((visibility("default"))` the visibility is already correct.
 138   The macro has an empty definition with GCC.
 139
 140   **Windows Behavior**: `extern template` and `dllexport` are fundamentally
 141   incompatible *on a class template* on Windows; the former suppresses
 142   instantiation, while the latter forces it. Specifying both on the same
 143   declaration makes the class template be instantiated, which is not desirable
 144   inside headers. This macro therefore expands to `dllimport` outside of libc++
 145   but nothing inside of it (rather than expanding to `dllexport`); instead, the
 146   explicit instantiations themselves are marked as exported. Note that this
 147   applies *only* to extern *class* templates. Extern *function* templates obey
 148   regular import/export semantics, and applying `dllexport` directly to the
 149   extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct
 150   thing to do for them.
 151
 152 **_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
 153   Mark the member functions, typeinfo, and vtable of an explicit instantiation
 154   of a class template as being exported by the libc++ library. This attribute
 155   must be specified on all class template explicit instantiations.
 156
 157   It is only necessary to mark the explicit instantiation itself (as opposed to
 158   the extern template declaration) as exported on Windows, as discussed above.
 159   On all other platforms, this macro has an empty definition.
 160
 161 **_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS**
 162   Mark a symbol as hidden so it will not be exported from shared libraries. This
 163   is intended specifically for method templates of either classes marked with
 164   `_LIBCPP_TYPE_VIS` or classes with an extern template instantiation
 165   declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`.
 166
 167   When building libc++ with hidden visibility, we want explicit template
 168   instantiations to export members, which is consistent with existing Windows
 169   behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export
 170   their members, which is again consistent with existing Windows behavior.
 171   Both these changes are necessary for clients to be able to link against a
 172   libc++ DSO built with hidden visibility without encountering missing symbols.
 173
 174   An unfortunate side effect, however, is that method templates of classes
 175   either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation
 176   declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default
 177   visibility when instantiated. These methods are often implicitly instantiated
 178   inside other libraries which use the libc++ headers, and will therefore end up
 179   being exported from those libraries, since those implicit instantiations will
 180   receive default visibility. This is not acceptable for libraries that wish to
 181   control their visibility, and led to PR30642.
 182
 183   Consequently, all such problematic method templates are explicitly marked
 184   either hidden (via this macro) or inline, so that they don't leak into client
 185   libraries. The problematic methods were found by running
 186   `bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_
 187   against the libc++ headers after making `_LIBCPP_TYPE_VIS` and
 188   `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility.
 189
 190 **_LIBCPP_EXCEPTION_ABI**
 191   Mark the member functions, typeinfo, and vtable of the type as being exported
 192   by the libc++ library. This macro must be applied to all *exception types*.
 193   Exception types should be defined directly in namespace `std` and not the
 194   versioning namespace. This allows throwing and catching some exception types
 195   between libc++ and libstdc++.
 196
 197 **_LIBCPP_INTERNAL_LINKAGE**
 198   Mark the affected entity as having internal linkage (i.e. the `static`
 199   keyword in C). This is only a best effort: when the `internal_linkage`
 200   attribute is not available, we fall back to forcing the function to be
 201   inlined, which approximates internal linkage since an externally visible
 202   symbol is never generated for that function. This is an internal macro
 203   used as an implementation detail by other visibility macros. Never mark
 204   a function or a class with this macro directly.
 205
 206 **_LIBCPP_ALWAYS_INLINE**
 207   Forces inlining of the function it is applied to. For visibility purposes,
 208   this macro is used to make sure that an externally visible symbol is never
 209   generated in an object file when the `internal_linkage` attribute is not
 210   available. This is an internal macro used by other visibility macros, and
 211   it should not be used directly.
 212
 213 Links
 214 =====
 215
 216 * `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_
 217 * `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_
 218 * `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_