1*4d6fc14bSjoerg===================== 2*4d6fc14bSjoergThreading Support API 3*4d6fc14bSjoerg===================== 4*4d6fc14bSjoerg 5*4d6fc14bSjoerg.. contents:: 6*4d6fc14bSjoerg :local: 7*4d6fc14bSjoerg 8*4d6fc14bSjoergOverview 9*4d6fc14bSjoerg======== 10*4d6fc14bSjoerg 11*4d6fc14bSjoergLibc++ supports using multiple different threading models and configurations 12*4d6fc14bSjoergto implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``. 13*4d6fc14bSjoergThese different models provide entirely different interfaces from each 14*4d6fc14bSjoergother. To address this libc++ wraps the underlying threading API in a new and 15*4d6fc14bSjoergconsistent API, which it uses internally to implement threading primitives. 16*4d6fc14bSjoerg 17*4d6fc14bSjoergThe ``<__threading_support>`` header is where libc++ defines its internal 18*4d6fc14bSjoergthreading interface. It contains forward declarations of the internal threading 19*4d6fc14bSjoerginterface as well as definitions for the interface. 20*4d6fc14bSjoerg 21*4d6fc14bSjoergExternal Threading API and the ``<__external_threading>`` header 22*4d6fc14bSjoerg================================================================ 23*4d6fc14bSjoerg 24*4d6fc14bSjoergIn order to support vendors with custom threading API's libc++ allows the 25*4d6fc14bSjoergentire internal threading interface to be provided by an external, 26*4d6fc14bSjoergvendor provided, header. 27*4d6fc14bSjoerg 28*4d6fc14bSjoergWhen ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__threading_support>`` 29*4d6fc14bSjoergheader simply forwards to the ``<__external_threading>`` header (which must exist). 30*4d6fc14bSjoergIt is expected that the ``<__external_threading>`` header provide the exact 31*4d6fc14bSjoerginterface normally provided by ``<__threading_support>``. 32*4d6fc14bSjoerg 33*4d6fc14bSjoergExternal Threading Library 34*4d6fc14bSjoerg========================== 35*4d6fc14bSjoerg 36*4d6fc14bSjoerglibc++ can be compiled with its internal threading API delegating to an external 37*4d6fc14bSjoerglibrary. Such a configuration is useful for library vendors who wish to 38*4d6fc14bSjoergdistribute a thread-agnostic libc++ library, where the users of the library are 39*4d6fc14bSjoergexpected to provide the implementation of the libc++ internal threading API. 40*4d6fc14bSjoerg 41*4d6fc14bSjoergOn a production setting, this would be achieved through a custom 42*4d6fc14bSjoerg``<__external_threading>`` header, which declares the libc++ internal threading 43*4d6fc14bSjoergAPI but leaves out the implementation. 44*4d6fc14bSjoerg 45*4d6fc14bSjoergThe ``-DLIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY`` option allows building libc++ in 46*4d6fc14bSjoergsuch a configuration while allowing it to be tested on a platform that supports 47*4d6fc14bSjoergany of the threading systems (e.g. pthread) supported in ``__threading_support`` 48*4d6fc14bSjoergheader. Therefore, the main purpose of this option is to allow testing of this 49*4d6fc14bSjoergparticular configuration of the library without being tied to a vendor-specific 50*4d6fc14bSjoergthreading system. This option is only meant to be used by libc++ library 51*4d6fc14bSjoergdevelopers. 52*4d6fc14bSjoerg 53*4d6fc14bSjoergThreading Configuration Macros 54*4d6fc14bSjoerg============================== 55*4d6fc14bSjoerg 56*4d6fc14bSjoerg**_LIBCPP_HAS_NO_THREADS** 57*4d6fc14bSjoerg This macro is defined when libc++ is built without threading support. It 58*4d6fc14bSjoerg should not be manually defined by the user. 59*4d6fc14bSjoerg 60*4d6fc14bSjoerg**_LIBCPP_HAS_THREAD_API_EXTERNAL** 61*4d6fc14bSjoerg This macro is defined when libc++ should use the ``<__external_threading>`` 62*4d6fc14bSjoerg header to provide the internal threading API. This macro overrides 63*4d6fc14bSjoerg ``_LIBCPP_HAS_THREAD_API_PTHREAD``. 64*4d6fc14bSjoerg 65*4d6fc14bSjoerg**_LIBCPP_HAS_THREAD_API_PTHREAD** 66*4d6fc14bSjoerg This macro is defined when libc++ should use POSIX threads to implement the 67*4d6fc14bSjoerg internal threading API. 68*4d6fc14bSjoerg 69*4d6fc14bSjoerg**_LIBCPP_HAS_THREAD_API_WIN32** 70*4d6fc14bSjoerg This macro is defined when libc++ should use Win32 threads to implement the 71*4d6fc14bSjoerg internal threading API. 72*4d6fc14bSjoerg 73*4d6fc14bSjoerg**_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL** 74*4d6fc14bSjoerg This macro is defined when libc++ expects the definitions of the internal 75*4d6fc14bSjoerg threading API to be provided by an external library. When defined 76*4d6fc14bSjoerg ``<__threading_support>`` will only provide the forward declarations and 77*4d6fc14bSjoerg typedefs for the internal threading API. 78*4d6fc14bSjoerg 79*4d6fc14bSjoerg**_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL** 80*4d6fc14bSjoerg This macro is used to build an external threading library using the 81*4d6fc14bSjoerg ``<__threading_support>``. Specifically it exposes the threading API 82*4d6fc14bSjoerg definitions in ``<__threading_support>`` as non-inline definitions meant to 83*4d6fc14bSjoerg be compiled into a library. 84