68 lines · plain
1=====================2Threading Support API3=====================4 5.. contents::6 :local:7 8Overview9========10 11Libc++ supports using multiple different threading models and configurations12to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``.13These different models provide entirely different interfaces from each14other. To address this libc++ wraps the underlying threading API in a new and15consistent API, which it uses internally to implement threading primitives.16 17The ``<__thread/support.h>`` header is where libc++ defines its internal18threading interface. It documents the functions and declarations required19to fullfil the internal threading interface.20 21External Threading API and the ``<__external_threading>`` header22================================================================23 24In order to support vendors with custom threading API's libc++ allows the25entire 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 exact31interface normally provided by ``<__thread/support.h>``.32 33External Threading Library34==========================35 36libc++ can be compiled with its internal threading API delegating to an external37library. Such a configuration is useful for library vendors who wish to38distribute a thread-agnostic libc++ library, where the users of the library are39expected to provide the implementation of the libc++ internal threading API.40 41On a production setting, this would be achieved through a custom42``<__external_threading>`` header, which declares the libc++ internal threading43API but leaves out the implementation.44 45Threading Configuration Macros46==============================47 48**_LIBCPP_HAS_THREADS**49 This macro is set to 1 when libc++ is built with threading support. Otherwise50 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 overrides55 ``_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 the59 internal threading API.60 61**_LIBCPP_HAS_THREAD_API_C11**62 This macro is defined when libc++ should use C11 threads to implement the63 internal threading API.64 65**_LIBCPP_HAS_THREAD_API_WIN32**66 This macro is defined when libc++ should use Win32 threads to implement the67 internal threading API.68