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_EXTERN_VIS** 26 Mark a symbol as being exported by the libc++ library. This attribute may 27 only be applied to objects defined in the libc++ library. On Windows this 28 macro applies `dllimport`/`dllexport` to the symbol. On all other platforms 29 this macro has no effect. 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_INLINE_VISIBILITY** 44 Mark a function as hidden and force inlining whenever possible. 45 46 **_LIBCPP_ALWAYS_INLINE** 47 A synonym for `_LIBCPP_INLINE_VISIBILITY` 48 49 **_LIBCPP_TYPE_VIS** 50 Mark a type's typeinfo, vtable and members as having default visibility. 51 This attribute cannot be used on class templates. 52 53 **_LIBCPP_TEMPLATE_VIS** 54 Mark a type's typeinfo and vtable as having default visibility. 55 This macro has no effect on the visibility of the type's member functions. 56 57 **GCC Behavior**: GCC does not support Clang's `type_visibility(...)` 58 attribute. With GCC the `visibility(...)` attribute is used and member 59 functions are affected. 60 61 **Windows Behavior**: DLLs do not support dllimport/export on class templates. 62 The macro has an empty definition on this platform. 63 64 65 **_LIBCPP_ENUM_VIS** 66 Mark the typeinfo of an enum as having default visibility. This attribute 67 should be applied to all enum declarations. 68 69 **Windows Behavior**: DLLs do not support importing or exporting enumeration 70 typeinfo. The macro has an empty definition on this platform. 71 72 **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even 73 if `-fvisibility=hidden` is specified. Additionally applying a visibility 74 attribute to an enum class results in a warning. The macro has an empty 75 definition with GCC. 76 77 **_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS** 78 Mark the member functions, typeinfo, and vtable of the type named in 79 a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library. 80 This attribute must be specified on all extern class template declarations. 81 82 This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute 83 specified on the primary template and to export the member functions produced 84 by the explicit instantiation in the dylib. 85 86 **GCC Behavior**: GCC ignores visibility attributes applied the type in 87 extern template declarations and applying an attribute results in a warning. 88 However since `_LIBCPP_TEMPLATE_VIS` is the same as 89 `__attribute__((visibility("default"))` the visibility is already correct. 90 The macro has an empty definition with GCC. 91 92 **Windows Behavior**: `extern template` and `dllexport` are fundamentally 93 incompatible *on a template class* on Windows; the former suppresses 94 instantiation, while the latter forces it. Specifying both on the same 95 declaration makes the template class be instantiated, which is not desirable 96 inside headers. This macro therefore expands to `dllimport` outside of libc++ 97 but nothing inside of it (rather than expanding to `dllexport`); instead, the 98 explicit instantiations themselves are marked as exported. Note that this 99 applies *only* to extern template *classes*. Extern template *functions* obey 100 regular import/export semantics, and applying `dllexport` directly to the 101 extern template declaration is the correct thing to do for them. 102 103 **_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS** 104 Mark the member functions, typeinfo, and vtable of an explicit instantiation 105 of a class template as being exported by the libc++ library. This attribute 106 must be specified on all template class explicit instantiations. 107 108 It is only necessary to mark the explicit instantiation itself (as opposed to 109 the extern template declaration) as exported on Windows, as discussed above. 110 On all other platforms, this macro has an empty definition. 111 112 **_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS** 113 Mark a symbol as hidden so it will not be exported from shared libraries. This 114 is intended specifically for method templates of either classes marked with 115 `_LIBCPP_TYPE_VIS` or classes with an extern template instantiation 116 declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`. 117 118 When building libc++ with hidden visibility, we want explicit template 119 instantiations to export members, which is consistent with existing Windows 120 behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export 121 their members, which is again consistent with existing Windows behavior. 122 Both these changes are necessary for clients to be able to link against a 123 libc++ DSO built with hidden visibility without encountering missing symbols. 124 125 An unfortunate side effect, however, is that method templates of classes 126 either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation 127 declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default 128 visibility when instantiated. These methods are often implicitly instantiated 129 inside other libraries which use the libc++ headers, and will therefore end up 130 being exported from those libraries, since those implicit instantiations will 131 receive default visibility. This is not acceptable for libraries that wish to 132 control their visibility, and led to PR30642. 133 134 Consequently, all such problematic method templates are explicitly marked 135 either hidden (via this macro) or inline, so that they don't leak into client 136 libraries. The problematic methods were found by running 137 `bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_ 138 against the libc++ headers after making `_LIBCPP_TYPE_VIS` and 139 `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility. 140 141 **_LIBCPP_EXTERN_TEMPLATE_INLINE_VISIBILITY** 142 Mark a member function of a class template as visible and always inline. This 143 macro should only be applied to member functions of class templates that are 144 externally instantiated. It is important that these symbols are not marked 145 as hidden as that will prevent the dylib definition from being found. 146 147 This macro is used to maintain ABI compatibility for symbols that have been 148 historically exported by the libc++ library but are now marked inline. 149 150 **_LIBCPP_EXCEPTION_ABI** 151 Mark the member functions, typeinfo, and vtable of the type as being exported 152 by the libc++ library. This macro must be applied to all *exception types*. 153 Exception types should be defined directly in namespace `std` and not the 154 versioning namespace. This allows throwing and catching some exception types 155 between libc++ and libstdc++. 156 157 Links 158 ===== 159 160 * `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_ 161 * `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_ 162 * `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_ 163
