libcxx/docs/DesignDocs/ThreadingSupportAPI.rst

   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 Threading Configuration Macros
  46 ==============================
  47
  48 **_LIBCPP_HAS_NO_THREADS**
  49   This macro is defined when libc++ is built without threading support. It
  50   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_WIN32**
  62   This macro is defined when libc++ should use Win32 threads to implement the
  63   internal threading API.