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