Threading Support API¶
Libc++ supports using multiple different threading models and configurations
to implement the threading parts of libc++, including
These different models provide entirely different interfaces from each
other. To address this libc++ wraps the underlying threading API in a new and
consistent API, which it uses internally to implement threading primitives.
<__threading_support> header is where libc++ defines its internal
threading interface. It contains forward declarations of the internal threading
interface as well as definitions for the interface.
In order to support vendors with custom threading API’s libc++ allows the entire internal threading interface to be provided by an external, vendor provided, header.
_LIBCPP_HAS_THREAD_API_EXTERNAL is defined the
header simply forwards to the
<__external_threading> header (which must exist).
It is expected that the
<__external_threading> header provide the exact
interface normally provided by
libc++ can be compiled with its internal threading API delegating to an external library. Such a configuration is useful for library vendors who wish to distribute a thread-agnostic libc++ library, where the users of the library are expected to provide the implementation of the libc++ internal threading API.
On a production setting, this would be achieved through a custom
<__external_threading> header, which declares the libc++ internal threading
API but leaves out the implementation.
-DLIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY option allows building libc++ in
such a configuration while allowing it to be tested on a platform that supports
any of the threading systems (e.g. pthread) supported in
header. Therefore, the main purpose of this option is to allow testing of this
particular configuration of the library without being tied to a vendor-specific
threading system. This option is only meant to be used by libc++ library
- This macro is defined when libc++ is built without threading support. It should not be manually defined by the user.
- This macro is defined when libc++ should use the
<__external_threading>header to provide the internal threading API. This macro overrides
- This macro is defined when libc++ should use POSIX threads to implement the internal threading API.
- This macro is defined when libc++ expects the definitions of the internal
threading API to be provided by an external library. When defined
<__threading_support>will only provide the forward declarations and typedefs for the internal threading API.
- This macro is used to build an external threading library using the
<__threading_support>. Specifically it exposes the threading API definitions in
<__threading_support>as non-inline definitions meant to be compiled into a library.