[libc++] Introduce _LIBCPP_HIDE_FROM_ABI to replace _LIBCPP_INLINE_VISIBILITY
Summary:
This commit introduces a new macro, _LIBCPP_HIDE_FROM_ABI, whose goal is to
mark functions that shouldn't be part of libc++'s ABI. It marks the functions
as being hidden for dylib visibility purposes, and as having internal linkage
using Clang's __attribute__((internal_linkage)) when available, and
__always_inline__ otherwise.
It replaces _LIBCPP_INLINE_VISIBILITY, which was always using __always_inline__
to achieve similar goals, but suffered from debuggability and code size problems.
The full proposal, along with more background information, can be found here:
http://lists.llvm.org/pipermail/cfe-dev/2018-July/058419.html
This commit does not rename uses of _LIBCPP_INLINE_VISIBILITY to
_LIBCPP_HIDE_FROM_ABI: this wide reaching but mechanical change can
be done later when we've confirmed we're happy with the new macro.
In the future, it would be nice if we could optionally allow dropping
any internal_linkage or __always_inline__ attribute, which could result
in code size improvements. However, this is currently impossible for
reasons explained here: http://lists.llvm.org/pipermail/cfe-dev/2018-July/058450.html
Reviewers: EricWF, dexonsmith, mclow.lists
Subscribers: christof, dexonsmith, llvm-commits, mclow.lists
Differential Revision: https://reviews.llvm.org/D49240
llvm-svn: 338122
Cr-Mirrored-From: sso://chromium.googlesource.com/_direct/external/github.com/llvm/llvm-project
Cr-Mirrored-Commit: cb3eb30636c8d9136c8a01126963eded45617531
diff --git a/docs/DesignDocs/VisibilityMacros.rst b/docs/DesignDocs/VisibilityMacros.rst
index 69a0997..878566e 100644
--- a/docs/DesignDocs/VisibilityMacros.rst
+++ b/docs/DesignDocs/VisibilityMacros.rst
@@ -40,7 +40,7 @@
this macro therefore expands to `__declspec(dllexport)` when building the
library and has an empty definition otherwise.
-**_LIBCPP_INLINE_VISIBILITY**
+**_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
@@ -155,6 +155,22 @@
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
=====