mirror of
https://github.com/llvm/llvm-project.git
synced 2025-04-29 13:36:09 +00:00
68 lines
2.6 KiB
ReStructuredText
68 lines
2.6 KiB
ReStructuredText
=====================
|
|
Threading Support API
|
|
=====================
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
Overview
|
|
========
|
|
|
|
Libc++ supports using multiple different threading models and configurations
|
|
to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``.
|
|
These different models provide entirely different interfaces from each
|
|
other. To address this libc++ wraps the underlying threading API in a new and
|
|
consistent API, which it uses internally to implement threading primitives.
|
|
|
|
The ``<__thread/support.h>`` header is where libc++ defines its internal
|
|
threading interface. It documents the functions and declarations required
|
|
to fullfil the internal threading interface.
|
|
|
|
External Threading API and the ``<__external_threading>`` header
|
|
================================================================
|
|
|
|
In order to support vendors with custom threading API's libc++ allows the
|
|
entire internal threading interface to be provided by an external,
|
|
vendor provided, header.
|
|
|
|
When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__thread/support.h>``
|
|
header simply forwards to the ``<__external_threading>`` header (which must exist).
|
|
It is expected that the ``<__external_threading>`` header provide the exact
|
|
interface normally provided by ``<__thread/support.h>``.
|
|
|
|
External Threading Library
|
|
==========================
|
|
|
|
libc++ can be compiled with its internal threading API delegating to an external
|
|
library. Such a configuration is useful for library vendors who wish to
|
|
distribute a thread-agnostic libc++ library, where the users of the library are
|
|
expected to provide the implementation of the libc++ internal threading API.
|
|
|
|
On a production setting, this would be achieved through a custom
|
|
``<__external_threading>`` header, which declares the libc++ internal threading
|
|
API but leaves out the implementation.
|
|
|
|
Threading Configuration Macros
|
|
==============================
|
|
|
|
**_LIBCPP_HAS_THREADS**
|
|
This macro is set to 1 when libc++ is built with threading support. Otherwise
|
|
it is set to 0. It should not be manually defined by the user.
|
|
|
|
**_LIBCPP_HAS_THREAD_API_EXTERNAL**
|
|
This macro is defined when libc++ should use the ``<__external_threading>``
|
|
header to provide the internal threading API. This macro overrides
|
|
``_LIBCPP_HAS_THREAD_API_PTHREAD``.
|
|
|
|
**_LIBCPP_HAS_THREAD_API_PTHREAD**
|
|
This macro is defined when libc++ should use POSIX threads to implement the
|
|
internal threading API.
|
|
|
|
**_LIBCPP_HAS_THREAD_API_C11**
|
|
This macro is defined when libc++ should use C11 threads to implement the
|
|
internal threading API.
|
|
|
|
**_LIBCPP_HAS_THREAD_API_WIN32**
|
|
This macro is defined when libc++ should use Win32 threads to implement the
|
|
internal threading API.
|