mirror of
https://github.com/llvm/llvm-project.git
synced 2025-04-28 13:56:08 +00:00
8ac71b026e
Our threading support layer is currently a huge mess. There are too many configurations with too many confusing names, and none of them are tested in the usual CI. Here's a list of names related to these configurations: LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY _LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL LIBCXXABI_BUILD_EXTERNAL_THREAD_LIBRARY _LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL LIBCXX_HAS_EXTERNAL_THREAD_API _LIBCPP_HAS_THREAD_API_EXTERNAL This patch cleans this up by removing the ability to build libc++ with an "external" threading library for testing purposes, removing 4 out of 6 "names" above. That setting was meant to be used by libc++ developers, but we don't use it in-tree and it's not part of our CI. I know the ability to use an external threading API is used by some folks out-of-tree, and this patch doesn't change that. This only changes the way they will have to test their external threading support. After this patch, the intent would be for them to set `-DLIBCXX_HAS_EXTERNAL_THREAD_API=ON` when building the library, and to provide their usual `<__external_threading>` header when they are testing the library. This can be done easily now that we support custom lit configuration files in test suites. The motivation for this patch is that our threading support layer is basically unmaintainable -- anything beyond adding a new "backend" in the slot designed for it requires incredible attention. The complexity added by this setting just doesn't pull its weigh considering the available alternatives. Concretely, this will also allow future patches to clean up `<__threading_support>` significantly. Differential Revision: https://reviews.llvm.org/D154466
64 lines
2.5 KiB
ReStructuredText
64 lines
2.5 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
|
|
==========================
|
|
|
|
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_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_API_WIN32**
|
|
This macro is defined when libc++ should use Win32 threads to implement the
|
|
internal threading API.
|