1 ===================== 2 Threading Support API 3 ===================== 4 5 .. contents:: 6 :local: 7 8 Overview 9 ======== 10 11 Libc++ supports using multiple different threading models and configurations 12 to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``. 13 These different models provide entirely different interfaces from each 14 other. To address this libc++ wraps the underlying threading API in a new and 15 consistent API, which it uses internally to implement threading primitives. 16 17 The ``<__threading_support>`` header is where libc++ defines its internal 18 threading interface. It contains forward declarations of the internal threading 19 interface as well as definitions for the interface. 20 21 External Threading API and the ``<__external_threading>`` header 22 ================================================================ 23 24 In order to support vendors with custom threading API's libc++ allows the 25 entire internal threading interface to be provided by an external, 26 vendor provided, header. 27 28 When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__threading_support>`` 29 header simply forwards to the ``<__external_threading>`` header (which must exist). 30 It is expected that the ``<__external_threading>`` header provide the exact 31 interface normally provided by ``<__threading_support>``. 32 33 External Threading Library 34 ========================== 35 36 libc++ can be compiled with its internal threading API delegating to an external 37 library. Such a configuration is useful for library vendors who wish to 38 distribute a thread-agnostic libc++ library, where the users of the library are 39 expected to provide the implementation of the libc++ internal threading API. 40 41 On a production setting, this would be achieved through a custom 42 ``<__external_threading>`` header, which declares the libc++ internal threading 43 API but leaves out the implementation. 44 45 The ``-DLIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY`` option allows building libc++ in 46 such a configuration while allowing it to be tested on a platform that supports 47 any of the threading systems (e.g. pthread) supported in ``__threading_support`` 48 header. Therefore, the main purpose of this option is to allow testing of this 49 particular configuration of the library without being tied to a vendor-specific 50 threading system. This option is only meant to be used by libc++ library 51 developers. 52 53 Threading 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
