How to adapt a parallel algorithm to C++20

1. Render the old overload under namespace parallel deprecated (e.g. hpx::parallel::for_each), according to the hpx deprecation headers. Be careful on referring to the pending HPX release version.

2. Change the base implementations (usually found as function objects under namespace hpx::parallel::v1::detail) in order to support iterator/sentinel pairs according to 3646 (just differenciate the type of last from the type of first).

3. Change the result type (if needed) on the base implementations. Mind not to create conflicts with the deprecated overloads. If there is no other way, change the result type on the deprecated overloads, too.

4. Add the C++20 overloads according to the C++20 Standard, using the tag_fallback/tag_fallback_invoke Customization Point Object (CPO) mechanism.

   1. If the algorithm has a segmented counterpart (under /libs/full/segmented_algorithms), provide the segmented overloads using tag_invoke instead of tag_fallback_invoke under namespace hpx::segmented and delete the dispatch functions (the ones with the underscore: e.g. for_each_).

5. Adapt the unit tests so they use the overloads under hpx and hpx::ranges namespaces.

   1. Mind to add tests for the overloads without an ExPolicy, in every test category (test_<algorithm>, test_<algorithm>_exception, test_<algorithm>_bad_alloc).
   2. Add tests that check the newly introduced iterator-sentinel_value overloads (test_<algorithm>_sent).

6. Provide docs for every given overload using the #if defined(DOXYGEN) - #else - #endif directives.

   1. Mind to pack the docs under namespace hpx or namespace hpx::ranges accordingly.
   2. Pay attention to the (possibly) altered result type.
   3. Be careful on documenting the overloads that do not have an ExPolicy. No parallelization is happening there.

Nitpicks and Tips

• For a given algorithm, the adaptation takes place both under /libs/parallelism/algorithms/include/hpx/parallel/algorithms/<algorithm>.hpp (non ranges overloads) and under /libs/parallelism/algorithms/include/hpx/parallel/container_algorithms/<algorithm>.hpp (ranges overloads).
• When documenting the adapted algorithms, cppreference is a good place to read about the effect of the algorithm.
• When documenting an algorithm under hpx::ranges namespace, that takes a Rng as an input source, there are no inherent first and last values. Mind to declare at the top that first is equivalent to parallel::util::begin(rng) and last is equivalent to parallel::util::end(rng).
• Disable clang-format for all the template parameters sections that include an HPX_CONCEPT_REQUIRES_ (// clang-format off/on) macro.
• Check our result types header for the newly introduced C++20 result types.
• We do not need any additional unit tests (overloads without an ExPolicy) for any of the _async tests.
• Provide static_assertions that check the validity of the iterators for every given overload: the ones with no ExPolicy usually use input iterators while the parallel ones use forward/bidirectional/random-access iterators.
• The previous bullet should be taken into consideration even for the Rng overloads. Here are some HPX custom facilities that provide an iterator-based interface for the Rng type.
• std::pair usually changes to hpx::parallel::util::in_out_result and std::tuple changes to hpx::parallel::util::in_in_out_result. std::distance, occasionally used on the base implementations, changes to detail::distance in order to support iterator/sentinel pairs.
• In order to test the iterator/sentinel-value case, you will need to include in the testing file, the iter_sent header like #include <hpx/iterator_support/tests/iter_sent.hpp>, which implements a custom sentinel facility.

This can be closed now! Thanks to everybody helping to implement, debug, and fix things!