Add documentation for the unpack sender adaptor

docs/api.rst

@@ -81,6 +81,12 @@ The ``pika/execution.hpp`` header provides functionality related to ``std::execu
    :language: c++
    :start-at: #include
 
+.. doxygenvariable:: pika::execution::experimental::unpack
+
+.. literalinclude:: ../examples/documentation/unpack_documentation.cpp
+   :language: c++
+   :start-at: #include
+
 .. doxygenvariable:: pika::execution::experimental::when_all_vector
 
 .. literalinclude:: ../examples/documentation/when_all_vector_documentation.cpp

examples/documentation/CMakeLists.txt

@@ -5,7 +5,7 @@
 # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 set(example_programs hello_world_documentation init_hpp_documentation split_tuple_documentation
-                     when_all_vector_documentation
+                     unpack_documentation when_all_vector_documentation
 )
 
 foreach(example_program ${example_programs})

examples/documentation/unpack_documentation.cpp

@@ -0,0 +1,44 @@
+//  Copyright (c) 2024 ETH Zurich
+//
+//  SPDX-License-Identifier: BSL-1.0
+//  Distributed under the Boost Software License, Version 1.0. (See accompanying
+//  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+#include <pika/execution.hpp>
+#include <pika/init.hpp>
+
+#include <fmt/printf.h>
+
+#include <tuple>
+#include <utility>
+
+int main(int argc, char* argv[])
+{
+    namespace ex = pika::execution::experimental;
+    namespace tt = pika::this_thread::experimental;
+
+    pika::start(argc, argv);
+    ex::thread_pool_scheduler sched{};
+
+    auto tuple_sender = ex::just(std::tuple(std::string("hello!"), 42)) | ex::continues_on(sched);
+    auto process_data = [](auto message, auto answer) {
+        fmt::print("{}\nthe answer is: {}\n", message, answer);
+    };
+
+    // With the unpack adaptor, process_data does not have to know that the data was originally sent
+    // as a tuple
+    auto unpack_sender = tuple_sender | ex::unpack() | ex::then(process_data);
+
+    // We can manually recreate the behaviour of the unpack adaptor by using std::apply. This is
+    // equivalent to the above.
+    auto apply_sender = tuple_sender | ex::then([&](auto tuple_of_data) {
+        return std::apply(process_data, std::move(tuple_of_data));
+    });
+
+    tt::sync_wait(ex::when_all(std::move(unpack_sender), std::move(apply_sender)));
+
+    pika::finalize();
+    pika::stop();
+
+    return 0;
+}

libs/pika/execution/include/pika/execution/algorithms/unpack.hpp

@@ -198,7 +198,7 @@ namespace pika::unpack_detail {
 }    // namespace pika::unpack_detail
 
 namespace pika::execution::experimental {
-    inline constexpr struct unpack_t final : pika::functional::detail::tag_fallback<unpack_t>
+    struct unpack_t final : pika::functional::detail::tag_fallback<unpack_t>
     {
     private:
         template <typename Sender, PIKA_CONCEPT_REQUIRES_(is_sender_v<Sender>)>
@@ -211,5 +211,16 @@ namespace pika::execution::experimental {
         {
             return detail::partial_algorithm<unpack_t>{};
         }
-    } unpack{};
+    };
+
+    /// \brief Transforms a sender of tuples into a sender of the elements of the tuples.
+    ///
+    /// Sender adaptor that takes a sender of tuple-likes and returns a sender where each tuple-like
+    /// has been unpacked into its elements, similarly to `std::apply`. Each completion signature
+    /// must send exactly one tuple-like, not zero or more than one. The adaptor does not unpack
+    /// tuple-likes recursively. Any type that supports the tuple protocol can be used with the
+    /// adaptor.
+    ///
+    /// Added in 0.17.0.
+    inline constexpr unpack_t unpack{};
 }    // namespace pika::execution::experimental