1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
========================
Symbol Visibility Macros
========================
.. contents::
:local:
Overview
========
Libc++ uses various "visibility" macros in order to provide a stable ABI in
both the library and the headers. These macros work by changing the
visibility and inlining characteristics of the symbols they are applied to.
Visibility Macros
=================
**_LIBCPP_HIDDEN**
Mark a symbol as hidden so it will not be exported from shared libraries.
**_LIBCPP_FUNC_VIS**
Mark a symbol as being exported by the libc++ library. This attribute must
be applied to the declaration of all functions exported by the libc++ dylib.
**_LIBCPP_EXTERN_VIS**
Mark a symbol as being exported by the libc++ library. This attribute may
only be applied to objects defined in the libc++ library. On Windows this
macro applies `dllimport`/`dllexport` to the symbol. On all other platforms
this macro has no effect.
**_LIBCPP_OVERRIDABLE_FUNC_VIS**
Mark a symbol as being exported by the libc++ library, but allow it to be
overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.
This macro is applied to all `operator new` and `operator delete` overloads.
**Windows Behavior**: Any symbol marked `dllimport` cannot be overridden
locally, since `dllimport` indicates the symbol should be bound to a separate
DLL. All `operator new` and `operator delete` overloads are required to be
locally overridable, and therefore must not be marked `dllimport`. On Windows,
this macro therefore expands to `__declspec(dllexport)` when building the
library and has an empty definition otherwise.
**_LIBCPP_HIDE_FROM_ABI**
Mark a function as not being part of the ABI of any final linked image that
uses it, and also as being internal to each TU that uses that function. In
other words, the address of a function marked with this attribute is not
guaranteed to be the same across translation units.
**_LIBCPP_TYPE_VIS**
Mark a type's typeinfo, vtable and members as having default visibility.
This attribute cannot be used on class templates.
**_LIBCPP_TEMPLATE_VIS**
Mark a type's typeinfo and vtable as having default visibility.
This macro has no effect on the visibility of the type's member functions.
**GCC Behavior**: GCC does not support Clang's `type_visibility(...)`
attribute. With GCC the `visibility(...)` attribute is used and member
functions are affected.
**Windows Behavior**: DLLs do not support dllimport/export on class templates.
The macro has an empty definition on this platform.
**_LIBCPP_ENUM_VIS**
Mark the typeinfo of an enum as having default visibility. This attribute
should be applied to all enum declarations.
**Windows Behavior**: DLLs do not support importing or exporting enumeration
typeinfo. The macro has an empty definition on this platform.
**GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even
if `-fvisibility=hidden` is specified. Additionally applying a visibility
attribute to an enum class results in a warning. The macro has an empty
definition with GCC.
**_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**
Mark the member functions, typeinfo, and vtable of the type named in
a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library.
This attribute must be specified on all extern class template declarations.
This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute
specified on the primary template and to export the member functions produced
by the explicit instantiation in the dylib.
**GCC Behavior**: GCC ignores visibility attributes applied the type in
extern template declarations and applying an attribute results in a warning.
However since `_LIBCPP_TEMPLATE_VIS` is the same as
`__attribute__((visibility("default"))` the visibility is already correct.
The macro has an empty definition with GCC.
**Windows Behavior**: `extern template` and `dllexport` are fundamentally
incompatible *on a class template* on Windows; the former suppresses
instantiation, while the latter forces it. Specifying both on the same
declaration makes the class template be instantiated, which is not desirable
inside headers. This macro therefore expands to `dllimport` outside of libc++
but nothing inside of it (rather than expanding to `dllexport`); instead, the
explicit instantiations themselves are marked as exported. Note that this
applies *only* to extern *class* templates. Extern *function* templates obey
regular import/export semantics, and applying `dllexport` directly to the
extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct
thing to do for them.
**_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
Mark the member functions, typeinfo, and vtable of an explicit instantiation
of a class template as being exported by the libc++ library. This attribute
must be specified on all class template explicit instantiations.
It is only necessary to mark the explicit instantiation itself (as opposed to
the extern template declaration) as exported on Windows, as discussed above.
On all other platforms, this macro has an empty definition.
**_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS**
Mark a symbol as hidden so it will not be exported from shared libraries. This
is intended specifically for method templates of either classes marked with
`_LIBCPP_TYPE_VIS` or classes with an extern template instantiation
declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`.
When building libc++ with hidden visibility, we want explicit template
instantiations to export members, which is consistent with existing Windows
behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export
their members, which is again consistent with existing Windows behavior.
Both these changes are necessary for clients to be able to link against a
libc++ DSO built with hidden visibility without encountering missing symbols.
An unfortunate side effect, however, is that method templates of classes
either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation
declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default
visibility when instantiated. These methods are often implicitly instantiated
inside other libraries which use the libc++ headers, and will therefore end up
being exported from those libraries, since those implicit instantiations will
receive default visibility. This is not acceptable for libraries that wish to
control their visibility, and led to PR30642.
Consequently, all such problematic method templates are explicitly marked
either hidden (via this macro) or inline, so that they don't leak into client
libraries. The problematic methods were found by running
`bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_
against the libc++ headers after making `_LIBCPP_TYPE_VIS` and
`_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility.
**_LIBCPP_EXTERN_TEMPLATE_INLINE_VISIBILITY**
Mark a member function of a class template as visible and always inline. This
macro should only be applied to member functions of class templates that are
externally instantiated. It is important that these symbols are not marked
as hidden as that will prevent the dylib definition from being found.
This macro is used to maintain ABI compatibility for symbols that have been
historically exported by the libc++ library but are now marked inline.
**_LIBCPP_EXCEPTION_ABI**
Mark the member functions, typeinfo, and vtable of the type as being exported
by the libc++ library. This macro must be applied to all *exception types*.
Exception types should be defined directly in namespace `std` and not the
versioning namespace. This allows throwing and catching some exception types
between libc++ and libstdc++.
**_LIBCPP_INTERNAL_LINKAGE**
Mark the affected entity as having internal linkage (i.e. the `static`
keyword in C). This is only a best effort: when the `internal_linkage`
attribute is not available, we fall back to forcing the function to be
inlined, which approximates internal linkage since an externally visible
symbol is never generated for that function. This is an internal macro
used as an implementation detail by other visibility macros. Never mark
a function or a class with this macro directly.
**_LIBCPP_ALWAYS_INLINE**
Forces inlining of the function it is applied to. For visibility purposes,
this macro is used to make sure that an externally visible symbol is never
generated in an object file when the `internal_linkage` attribute is not
available. This is an internal macro used by other visibility macros, and
it should not be used directly.
Links
=====
* `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_
* `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_
* `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_
|
