From 43e57f0ed0e284126292d977b0c54935eaec1a7e Mon Sep 17 00:00:00 2001
From: Mikael Simberg <mikael.simberg@iki.fi>
Date: Wed, 23 Oct 2024 15:49:30 +0200
Subject: [PATCH] Add documentation for the unpack sender adaptor

---
 docs/api.rst                                  |  6 +++
 examples/documentation/CMakeLists.txt         |  2 +-
 .../documentation/unpack_documentation.cpp    | 45 +++++++++++++++++++
 .../pika/execution/algorithms/unpack.hpp      | 15 ++++++-
 4 files changed, 65 insertions(+), 3 deletions(-)
 create mode 100644 examples/documentation/unpack_documentation.cpp

diff --git a/docs/api.rst b/docs/api.rst
index d746c054f5..d12d0cd688 100644
--- a/docs/api.rst
+++ b/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
diff --git a/examples/documentation/CMakeLists.txt b/examples/documentation/CMakeLists.txt
index 78d198aa0c..f706353b67 100644
--- a/examples/documentation/CMakeLists.txt
+++ b/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})
diff --git a/examples/documentation/unpack_documentation.cpp b/examples/documentation/unpack_documentation.cpp
new file mode 100644
index 0000000000..4d812ecd4e
--- /dev/null
+++ b/examples/documentation/unpack_documentation.cpp
@@ -0,0 +1,45 @@
+//  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 <string>
+#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;
+}
diff --git a/libs/pika/execution/include/pika/execution/algorithms/unpack.hpp b/libs/pika/execution/include/pika/execution/algorithms/unpack.hpp
index 0d9f04941d..25889616d6 100644
--- a/libs/pika/execution/include/pika/execution/algorithms/unpack.hpp
+++ b/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