[libcxx-commits] [libcxx] 5c6be1d - [libc++][PSTL] Add design docs

[Nikolas Klauser via libcxx-commits]

Author: Nikolas Klauser
Date: 2023-05-03T15:25:47-07:00
New Revision: 5c6be1d48c15c012c8f7fc44b10385b53f343806

URL: https://github.com/llvm/llvm-project/commit/5c6be1d48c15c012c8f7fc44b10385b53f343806
DIFF: https://github.com/llvm/llvm-project/commit/5c6be1d48c15c012c8f7fc44b10385b53f343806.diff

LOG: [libc++][PSTL] Add design docs

Reviewed By: ldionne, Mordante, #libc

Spies: grandinj, libcxx-commits, arphaman

Differential Revision: https://reviews.llvm.org/D148478

Added: 
    libcxx/docs/DesignDocs/PSTLIntegration.rst

Modified: 
    libcxx/docs/index.rst

Removed: 
    


################################################################################
diff  --git a/libcxx/docs/DesignDocs/PSTLIntegration.rst b/libcxx/docs/DesignDocs/PSTLIntegration.rst
new file mode 100644
index 0000000000000..e2b9e89f050eb
--- /dev/null
+++ b/libcxx/docs/DesignDocs/PSTLIntegration.rst
@@ -0,0 +1,22 @@
+================
+PSTL integration
+================
+
+The PSTL (or Parallel STL) project is quite complex in its current form and does not provide everything that libc++
+requires, for example ``_LIBCPP_HIDE_FROM_ABI`` or similar annotations and including granularized headers. Furthermore,
+the PSTL provides various layers of indirection that make sense in a generic implementation of the parallel algorithms,
+but are unnecessarily complex in the context of a single standard library implementation. Because of these drawbacks, we
+decided to adopt a modified PSTL in libc++. Specifically, the goals of the modified PSTL are
+
+- No ``<__pstl_algorithm>`` and similar glue headers -- instead, the implementation files are included directly in
+  ``<algorithm>`` and friends.
+- No ``<pstl/internal/algorithm_impl.h>`` and ``<pstl/internal/algorithm_fwd.h>`` headers and friends -- these contain
+  the implementation and forward declarations for internal functions respectively. The implementation lives inside
+  ``<__algorithm/pstl_any_of.h>`` and friends, and the forward declarations are not needed inside libc++.
+- No ``<pstl/internal/glue_algorithm_defs.h>`` and ``<pstl/internal/glue_algorithm_impl.h>`` headers and friends --
+  these contain the public API. It lives inside ``<__algorithm/pstl_any_of.h>`` and friends instead.
+- The headers implementing backends are kept with as few changes as possible to make it easier to keep the backends in
+  sync with the backends from the original PSTL.
+- The configuration headers ``__pstl_config_site.in`` and ``pstl_config.h`` are removed, and any required configuration
+  is done inside ``__config_site.in`` and ``__config`` respectively.
+- libc++-style tests for the public PSTL API

diff  --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst
index 6fa35d4ed40e8..4af4d9f1704f5 100644
--- a/libcxx/docs/index.rst
+++ b/libcxx/docs/index.rst
@@ -179,6 +179,7 @@ Design Documents
    DesignDocs/FileTimeType
    DesignDocs/HeaderRemovalPolicy
    DesignDocs/NoexceptPolicy
+   DesignDocs/PSTLIntegration
    DesignDocs/ThreadingSupportAPI
    DesignDocs/UniquePtrTrivialAbi
    DesignDocs/UnspecifiedBehaviorRandomization