1=====================
2Threading Support API
3=====================
4
5.. contents::
6   :local:
7
8Overview
9========
10
11Libc++ supports using multiple different threading models and configurations
12to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``.
13These different models provide entirely different interfaces from each
14other. To address this libc++ wraps the underlying threading API in a new and
15consistent API, which it uses internally to implement threading primitives.
16
17The ``<__threading_support>`` header is where libc++ defines its internal
18threading interface. It contains forward declarations of the internal threading
19interface as well as definitions for the interface.
20
21External Threading API and the ``<__external_threading>`` header
22================================================================
23
24In order to support vendors with custom threading API's libc++ allows the
25entire internal threading interface to be provided by an external,
26vendor provided, header.
27
28When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__threading_support>``
29header simply forwards to the ``<__external_threading>`` header (which must exist).
30It is expected that the ``<__external_threading>`` header provide the exact
31interface normally provided by ``<__threading_support>``.
32
33External Threading Library
34==========================
35
36Normally ``<__threading_support>`` provides inline definitions to each internal
37threading API function it declares. However libc++ also supports using an
38external library to provide the definitions.
39
40When ``_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL`` libc++ does not provide inline
41definitions for the internal API, instead assuming the definitions will be
42provided by an external library.
43
44Threading Configuration Macros
45==============================
46
47**_LIBCPP_HAS_NO_THREADS**
48  This macro is defined when libc++ is built without threading support. It
49  should not be manually defined by the user.
50
51**_LIBCPP_HAS_THREAD_API_EXTERNAL**
52  This macro is defined when libc++ should use the ``<__external_threading>``
53  header to provide the internal threading API. This macro overrides
54  ``_LIBCPP_HAS_THREAD_API_PTHREAD``.
55
56**_LIBCPP_HAS_THREAD_API_PTHREAD**
57  This macro is defined when libc++ should use POSIX threads to implement the
58  internal threading API.
59
60**_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL**
61  This macro is defined when libc++ expects the definitions of the internal
62  threading API to be provided by an external library. When defined
63  ``<__threading_support>`` will only provide the forward declarations and
64  typedefs for the internal threading API.
65
66**_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL**
67  This macro is used to build an external threading library using the
68  ``<__threading_support>``. Specifically it exposes the threading API
69  definitions in ``<__threading_support>`` as non-inline definitions meant to
70  be compiled into a library.
71