Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[libc++] Cleanup and document <__threading_support>
Summary: This patch attempts to clean up the macro configuration mess in `<__threading_support>`, specifically the mess involving external threading variants. Additionally this patch adds design documentation for `<__threading_support>` and the configuration macros it uses. The primary change in this patch is separating the idea of an "external API" provided by `<__external_threading>` and the idea of having an external threading library. Now `_LIBCPP_HAS_THREAD_API_EXTERNAL` means that libc++ should use `<__external_threading>` and that the header is expected to exist. Additionally the new macro `_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL` is now used to configure for using an "external library" with the default threading API. Reviewers: compnerd, rmaprath Subscribers: smeenai, cfe-commits, mgorny Differential Revision: https://reviews.llvm.org/D28316 llvm-svn: 291275
- Loading branch information
Showing
10 changed files
with
111 additions
and
46 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,70 @@ | ||
===================== | ||
Threading Support API | ||
===================== | ||
|
||
.. contents:: | ||
:local: | ||
|
||
Overview | ||
======== | ||
|
||
Libc++ supports using multiple different threading models and configurations | ||
to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``. | ||
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. | ||
|
||
The ``<__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. | ||
|
||
External Threading API and the ``<__external_threading>`` header | ||
================================================================ | ||
|
||
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. | ||
|
||
When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__threading_support>`` | ||
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 ``<__threading_support>``. | ||
|
||
External Threading Library | ||
========================== | ||
|
||
Normally ``<__threading_support>`` provides inline definitions to each internal | ||
threading API function it declares. However libc++ also supports using an | ||
external library to provide the definitions. | ||
|
||
When ``_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL`` libc++ does not provide inline | ||
definitions for the internal API, instead assuming the definitions will be | ||
provided by an external library. | ||
|
||
Threading Configuration Macros | ||
============================== | ||
|
||
**_LIBCPP_HAS_NO_THREADS** | ||
This macro is defined when libc++ is built without threading support. It | ||
should not be manually defined by the user. | ||
|
||
**_LIBCPP_HAS_THREAD_API_EXTERNAL** | ||
This macro is defined when libc++ should use the ``<__external_threading>`` | ||
header to provide the internal threading API. This macro overrides | ||
``_LIBCPP_HAS_THREAD_API_PTHREAD``. | ||
|
||
**_LIBCPP_HAS_THREAD_API_PTHREAD** | ||
This macro is defined when libc++ should use POSIX threads to implement the | ||
internal threading API. | ||
|
||
**_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL** | ||
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. | ||
|
||
**_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL** | ||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters