LTO Visibility
LTO visibility is a property of an entity that specifies whether it can be referenced from outside the current LTO unit. A linkage unit is a set of translation units linked together into an executable or DSO, and a linkage unit's LTO unit is the subset of the linkage unit that is linked together using link-time optimization; in the case where LTO is not being used, the linkage unit's LTO unit is empty. Each linkage unit has only a single LTO unit.
The LTO visibility of a class is used by the compiler to determine which
classes the whole-program devirtualization (-fwhole-program-vtables) and
control flow integrity (-fsanitize=cfi-vcall and -fsanitize=cfi-mfcall)
features apply to. These features use whole-program information, so they
require the entire class hierarchy to be visible in order to work correctly.
If any translation unit in the program uses either of the whole-program devirtualization or control flow integrity features, it is effectively an ODR violation to define a class with hidden LTO visibility in multiple linkage units. A class with public LTO visibility may be defined in multiple linkage units, but the tradeoff is that the whole-program devirtualization and control flow integrity features can only be applied to classes with hidden LTO visibility. A class's LTO visibility is treated as an ODR-relevant property of its definition, so it must be consistent between translation units.
In translation units built with LTO, LTO visibility is based on the
class's symbol visibility as expressed at the source level (i.e. the
__attribute__((visibility("..."))) attribute, or the -fvisibility=
flag) or, on the Windows platform, the dllimport and dllexport attributes. When
targeting non-Windows platforms, classes with a visibility other than hidden
visibility receive public LTO visibility. When targeting Windows, classes
with dllimport or dllexport attributes receive public LTO visibility. All
other classes receive hidden LTO visibility. Classes with internal linkage
(e.g. classes declared in unnamed namespaces) also receive hidden LTO
visibility.
During the LTO link, all classes with public LTO visibility will be refined
to hidden LTO visibility when the --lto-whole-program-visibility lld linker
option is applied (-plugin-opt=whole-program-visibility for gold). This flag
can be used to defer specifying whether classes have hidden LTO visibility until
link time, to allow bitcode objects to be shared by different LTO links.
Due to an implementation limitation, symbols associated with classes with hidden
LTO visibility may still be exported from the binary when using this flag. It is
unsafe to refer to these symbols, and their visibility may be relaxed to hidden
in a future compiler release.
A class defined in a translation unit built without LTO receives public LTO visibility regardless of its object file visibility, linkage or other attributes.
This mechanism will produce the correct result in most cases, but there are two cases where it may wrongly infer hidden LTO visibility.
- As a corollary of the above rules, if a linkage unit is produced from a combination of LTO object files and non-LTO object files, any hidden visibility class defined in both a translation unit built with LTO and a translation unit built without LTO must be defined with public LTO visibility in order to avoid an ODR violation.
- Some ABIs provide the ability to define an abstract base class without visibility attributes in multiple linkage units and have virtual calls to derived classes in other linkage units work correctly. One example of this is COM on Windows platforms. If the ABI allows this, any base class used in this way must be defined with public LTO visibility.
Classes that fall into either of these categories can be marked up with the
[[clang::lto_visibility_public]] attribute. To specifically handle the
COM case, classes with the __declspec(uuid()) attribute receive public
LTO visibility. On Windows platforms, clang-cl's /MT and /MTd
flags statically link the program against a prebuilt standard library;
these flags imply public LTO visibility for every class declared in the
std and stdext namespaces.
Example
The following example shows how LTO visibility works in practice in several
cases involving two linkage units, main and dso.so.
+-----------------------------------------------------------+ +----------------------------------------------------+
| main (clang++ -fvisibility=hidden): | | dso.so (clang++ -fvisibility=hidden): |
| | | |
| +-----------------------------------------------------+ | | struct __attribute__((visibility("default"))) C { |
| | LTO unit (clang++ -fvisibility=hidden -flto): | | | virtual void f(); |
| | | | | } |
| | struct A { ... }; | | | void C::f() {} |
| | struct [[clang::lto_visibility_public]] B { ... }; | | | struct D { |
| | struct __attribute__((visibility("default"))) C { | | | virtual void g() = 0; |
| | virtual void f(); | | | }; |
| | }; | | | struct E : D { |
| | struct [[clang::lto_visibility_public]] D { | | | virtual void g() { ... } |
| | virtual void g() = 0; | | | }; |
| | }; | | | __attribute__((visibility("default"))) D *mkE() { |
| | | | | return new E; |
| +-----------------------------------------------------+ | | } |
| | | |
| struct B { ... }; | +----------------------------------------------------+
| |
+-----------------------------------------------------------+
We will now describe the LTO visibility of each of the classes defined in these linkage units.
Class A is not defined outside of main's LTO unit, so it can have
hidden LTO visibility. This is inferred from the object file visibility
specified on the command line.
Class B is defined in main, both inside and outside its LTO unit. The
definition outside the LTO unit has public LTO visibility, so the definition
inside the LTO unit must also have public LTO visibility in order to avoid
an ODR violation.
Class C is defined in both main and dso.so and therefore must
have public LTO visibility. This is correctly inferred from the visibility
attribute.
Class D is an abstract base class with a derived class E defined
in dso.so. This is an example of the COM scenario; the definition of
D in main's LTO unit must have public LTO visibility in order to be
compatible with the definition of D in dso.so, which is observable
by calling the function mkE.