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 ``<__thread/support.h>`` header is where libc++ defines its internal 18threading interface. It documents the functions and declarations required 19to fullfil the internal threading 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 ``<__thread/support.h>`` 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 ``<__thread/support.h>``. 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 45Threading Configuration Macros 46============================== 47 48**_LIBCPP_HAS_THREADS** 49 This macro is set to 1 when libc++ is built with threading support. Otherwise 50 it is set to 0. It should not be manually defined by the user. 51 52**_LIBCPP_HAS_THREAD_API_EXTERNAL** 53 This macro is defined when libc++ should use the ``<__external_threading>`` 54 header to provide the internal threading API. This macro overrides 55 ``_LIBCPP_HAS_THREAD_API_PTHREAD``. 56 57**_LIBCPP_HAS_THREAD_API_PTHREAD** 58 This macro is defined when libc++ should use POSIX threads to implement the 59 internal threading API. 60 61**_LIBCPP_HAS_THREAD_API_C11** 62 This macro is defined when libc++ should use C11 threads to implement the 63 internal threading API. 64 65**_LIBCPP_HAS_THREAD_API_WIN32** 66 This macro is defined when libc++ should use Win32 threads to implement the 67 internal threading API. 68