Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | dae3960 | 2017-01-16 21:01:00 +0000 | [diff] [blame^] | 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 | |
Shoaib Meenai | e6479bc | 2016-11-16 22:18:10 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 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 and vtable as having default visibility. |
| 51 | `_LIBCPP_TYPE_VIS`. This macro has no effect on the visibility of the |
| 52 | type's member functions. This attribute cannot be used on class templates. |
| 53 | |
| 54 | **GCC Behavior**: GCC does not support Clang's `type_visibility(...)` |
| 55 | attribute. With GCC the `visibility(...)` attribute is used and member |
| 56 | functions are affected. |
| 57 | |
Shoaib Meenai | 2342c11 | 2017-01-07 02:45:35 +0000 | [diff] [blame] | 58 | **_LIBCPP_TEMPLATE_VIS** |
Eric Fiselier | c3589a8 | 2017-01-04 23:56:00 +0000 | [diff] [blame] | 59 | The same as `_LIBCPP_TYPE_VIS` except that it may be applied to class |
| 60 | templates. |
Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 61 | |
| 62 | **Windows Behavior**: DLLs do not support dllimport/export on class templates. |
| 63 | The macro has an empty definition on this platform. |
| 64 | |
Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 65 | |
| 66 | **_LIBCPP_ENUM_VIS** |
| 67 | Mark the typeinfo of an enum as having default visibility. This attribute |
| 68 | should be applied to all enum declarations. |
| 69 | |
| 70 | **Windows Behavior**: DLLs do not support importing or exporting enumeration |
| 71 | typeinfo. The macro has an empty definition on this platform. |
| 72 | |
| 73 | **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even |
| 74 | if `-fvisibility=hidden` is specified. Additionally applying a visibility |
| 75 | attribute to an enum class results in a warning. The macro has an empty |
| 76 | definition with GCC. |
| 77 | |
| 78 | **_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS** |
| 79 | Mark the member functions, typeinfo, and vtable of the type named in |
| 80 | a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library. |
| 81 | This attribute must be specified on all extern class template declarations. |
| 82 | |
Eric Fiselier | c3589a8 | 2017-01-04 23:56:00 +0000 | [diff] [blame] | 83 | This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute |
Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 84 | specified on the primary template and to export the member functions produced |
| 85 | by the explicit instantiation in the dylib. |
| 86 | |
| 87 | **GCC Behavior**: GCC ignores visibility attributes applied the type in |
| 88 | extern template declarations and applying an attribute results in a warning. |
Eric Fiselier | a2e3d1e | 2017-01-05 00:04:37 +0000 | [diff] [blame] | 89 | However since `_LIBCPP_TEMPLATE_VIS` is the same as |
Eric Fiselier | c3589a8 | 2017-01-04 23:56:00 +0000 | [diff] [blame] | 90 | `__attribute__((visibility("default"))` the visibility is already correct. |
| 91 | The macro has an empty definition with GCC. |
Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 92 | |
Shoaib Meenai | e5cbce4 | 2016-09-19 18:29:07 +0000 | [diff] [blame] | 93 | **Windows Behavior**: `extern template` and `dllexport` are fundamentally |
| 94 | incompatible *on a template class* on Windows; the former suppresses |
| 95 | instantiation, while the latter forces it. Specifying both on the same |
| 96 | declaration makes the template class be instantiated, which is not desirable |
| 97 | inside headers. This macro therefore expands to `dllimport` outside of libc++ |
| 98 | but nothing inside of it (rather than expanding to `dllexport`); instead, the |
| 99 | explicit instantiations themselves are marked as exported. Note that this |
| 100 | applies *only* to extern template *classes*. Extern template *functions* obey |
| 101 | regular import/export semantics, and applying `dllexport` directly to the |
| 102 | extern template declaration is the correct thing to do for them. |
| 103 | |
| 104 | **_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS** |
| 105 | Mark the member functions, typeinfo, and vtable of an explicit instantiation |
| 106 | of a class template as being exported by the libc++ library. This attribute |
| 107 | must be specified on all template class explicit instantiations. |
| 108 | |
| 109 | It is only necessary to mark the explicit instantiation itself (as opposed to |
| 110 | the extern template declaration) as exported on Windows, as discussed above. |
| 111 | On all other platforms, this macro has an empty definition. |
| 112 | |
Eric Fiselier | 6dbed46 | 2016-09-16 00:00:48 +0000 | [diff] [blame] | 113 | **_LIBCPP_EXTERN_TEMPLATE_INLINE_VISIBILITY** |
Eric Fiselier | eb6b13f | 2016-10-31 02:07:23 +0000 | [diff] [blame] | 114 | Mark a member function of a class template as visible and always inline. This |
| 115 | macro should only be applied to member functions of class templates that are |
| 116 | externally instantiated. It is important that these symbols are not marked |
| 117 | as hidden as that will prevent the dylib definition from being found. |
Eric Fiselier | 6dbed46 | 2016-09-16 00:00:48 +0000 | [diff] [blame] | 118 | |
| 119 | This macro is used to maintain ABI compatibility for symbols that have been |
Eric Fiselier | eb6b13f | 2016-10-31 02:07:23 +0000 | [diff] [blame] | 120 | historically exported by the libc++ library but are now marked inline. |
Eric Fiselier | 6dbed46 | 2016-09-16 00:00:48 +0000 | [diff] [blame] | 121 | |
Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 122 | **_LIBCPP_EXCEPTION_ABI** |
| 123 | Mark the member functions, typeinfo, and vtable of the type as being exported |
| 124 | by the libc++ library. This macro must be applied to all *exception types*. |
Eric Fiselier | 65d504e | 2016-09-16 02:51:26 +0000 | [diff] [blame] | 125 | Exception types should be defined directly in namespace `std` and not the |
| 126 | versioning namespace. This allows throwing and catching some exception types |
| 127 | between libc++ and libstdc++. |
Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 128 | |
Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 129 | Links |
| 130 | ===== |
| 131 | |
| 132 | * `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_ |
| 133 | * `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_ |
| 134 | * `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_ |