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
36libc++ can be compiled with its internal threading API delegating to an external
37library. Such a configuration is useful for library vendors who wish to
38distribute a thread-agnostic libc++ library, where the users of the library are
39expected to provide the implementation of the libc++ internal threading API.
40
41On a production setting, this would be achieved through a custom
42``<__external_threading>`` header, which declares the libc++ internal threading
43API but leaves out the implementation.
44
45The ``-DLIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY`` option allows building libc++ in
46such a configuration while allowing it to be tested on a platform that supports
47any of the threading systems (e.g. pthread) supported in ``__threading_support``
48header. Therefore, the main purpose of this option is to allow testing of this
49particular configuration of the library without being tied to a vendor-specific
50threading system. This option is only meant to be used by libc++ library
51developers.
52
53Threading Configuration Macros
54==============================
55
56**_LIBCPP_HAS_NO_THREADS**
57  This macro is defined when libc++ is built without threading support. It
58  should not be manually defined by the user.
59
60**_LIBCPP_HAS_THREAD_API_EXTERNAL**
61  This macro is defined when libc++ should use the ``<__external_threading>``
62  header to provide the internal threading API. This macro overrides
63  ``_LIBCPP_HAS_THREAD_API_PTHREAD``.
64
65**_LIBCPP_HAS_THREAD_API_PTHREAD**
66  This macro is defined when libc++ should use POSIX threads to implement the
67  internal threading API.
68
69**_LIBCPP_HAS_THREAD_API_WIN32**
70  This macro is defined when libc++ should use Win32 threads to implement the
71  internal threading API.
72
73**_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL**
74  This macro is defined when libc++ expects the definitions of the internal
75  threading API to be provided by an external library. When defined
76  ``<__threading_support>`` will only provide the forward declarations and
77  typedefs for the internal threading API.
78
79**_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL**
80  This macro is used to build an external threading library using the
81  ``<__threading_support>``. Specifically it exposes the threading API
82  definitions in ``<__threading_support>`` as non-inline definitions meant to
83  be compiled into a library.
84