[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
git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@291275 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/DesignDocs/ThreadingSupportAPI.rst b/docs/DesignDocs/ThreadingSupportAPI.rst
new file mode 100644
index 0000000..77ec6bc
--- /dev/null
+++ b/docs/DesignDocs/ThreadingSupportAPI.rst
@@ -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.