mirror of
https://github.com/llvm/llvm-project.git
synced 2025-05-01 03:06:07 +00:00
71 lines
2.8 KiB
ReStructuredText
71 lines
2.8 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 ``<__threading_support>`` header is where libc++ defines its internal
|
||
|
|
threading interface. It contains forward declarations of the internal threading
|
||
|
|
interface as well as definitions for the 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 ``<__threading_support>``
|
||
|
|
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 ``<__threading_support>``.
|
||
|
|
|
||
|
|
External Threading Library
|
||
|
|
==========================
|
||
|
|
|
||
|
|
Normally ``<__threading_support>`` provides inline definitions to each internal
|
||
|
|
threading API function it declares. However libc++ also supports using an
|
||
|
|
external library to provide the definitions.
|
||
|
|
|
||
|
|
When ``_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL`` libc++ does not provide inline
|
||
|
|
definitions for the internal API, instead assuming the definitions will be
|
||
|
|
provided by an external library.
|
||
|
|
|
||
|
|
Threading Configuration Macros
|
||
|
|
==============================
|
||
|
|
|
||
|
|
**_LIBCPP_HAS_NO_THREADS**
|
||
|
|
This macro is defined when libc++ is built without threading support. 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_LIBRARY_EXTERNAL**
|
||
|
|
This macro is defined when libc++ expects the definitions of the internal
|
||
|
|
threading API to be provided by an external library. When defined
|
||
|
|
``<__threading_support>`` will only provide the forward declarations and
|
||
|
|
typedefs for the internal threading API.
|
||
|
|
|
||
|
|
**_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL**
|
||
|
|
This macro is used to build an external threading library using the
|
||
|
|
``<__threading_support>``. Specifically it exposes the threading API
|
||
|
|
definitions in ``<__threading_support>`` as non-inline definitions meant to
|
||
|
|
be compiled into a library.
|