From 27377f754e387a5a0e05e82f4a9e2e9e1c98e00e Mon Sep 17 00:00:00 2001
From: Ben Deane <ben@elbeno.com>
Date: Tue, 26 Nov 2024 10:58:03 -0700
Subject: [PATCH] :sparkles: Add `into_variant`

---
 docs/sender_adaptors.adoc      |  23 ++++
 docs/synopsis.adoc             |   4 +
 include/async/into_variant.hpp | 130 +++++++++++++++++++
 test/CMakeLists.txt            |   1 +
 test/into_variant.cpp          | 222 +++++++++++++++++++++++++++++++++
 5 files changed, 380 insertions(+)
 create mode 100644 include/async/into_variant.hpp
 create mode 100644 test/into_variant.cpp

diff --git a/docs/sender_adaptors.adoc b/docs/sender_adaptors.adoc
index 3b9881e..7e9c8ea 100644
--- a/docs/sender_adaptors.adoc
+++ b/docs/sender_adaptors.adoc
@@ -63,6 +63,29 @@ NOTE: The incited scheduler must produce a sender which completes
 asynchronously. A synchronous scheduler would require no incitement, and
 `continue_on` would be correct.
 
+=== `into_variant`
+
+Found in the header: `async/into_variant.hpp`
+
+`into_variant` adapts a sender that has several possible value completions into
+a sender with a single value completion that is a variant of tuples, where each
+tuple represents one of the original sender's value completions.
+
+[source,cpp]
+----
+auto sndr = async::make_variant_sender(
+                selection,
+                [] { return async::just(42, 17); },
+                [] { return async::just(2.718f, 3.14f); })
+          | async::into_variant();
+
+// sndr will complete with set_value(variant<tuple<int, int>, tuple<float, float>>)
+----
+
+NOTE: Some sender consumers (like
+xref:sender_consumers.adoc#_sync_wait[`sync_wait`]) require the sender to have
+one possible value completion.
+
 === `let_error`
 
 Found in the header: `async/let_error.hpp`
diff --git a/docs/synopsis.adoc b/docs/synopsis.adoc
index a142e1f..d805a96 100644
--- a/docs/synopsis.adoc
+++ b/docs/synopsis.adoc
@@ -61,6 +61,9 @@ in pipe-composition syntax.
 ==== https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/incite_on.hpp[incite_on.hpp]
 * `incite_on` - a xref:sender_adaptors.adoc#_incite_on[sender adaptor] that incites execution on another scheduler
 
+==== https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/into_variant.hpp[into_variant.hpp]
+* `into_variant` - a xref:sender_adaptors.adoc#_into_variant[sender adaptor] that collapses value completions into a variant
+
 ==== https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/just.hpp[just.hpp]
 * `just` - a xref:sender_factories.adoc#_just[sender factory] that sends on the value channel
 * `just_error` - a xref:sender_factories.adoc#_just_error[sender factory] that sends on the error channel
@@ -230,6 +233,7 @@ contains traits and metaprogramming constructs used by many senders.
 * xref:schedulers.adoc#_inline_scheduler[`inline_scheduler`] - https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/schedulers/inline_scheduler.hpp[`#include <async/schedulers/inline_scheduler.hpp>`]
 * `inplace_stop_source` - https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/schedulers/stop_token.hpp[`#include <async/stop_token.hpp>`]
 * `inplace_stop_token`- https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/schedulers/stop_token.hpp[`#include <async/stop_token.hpp>`]
+* xref:sender_adaptors.adoc#_into_variant[`into_variant`] - https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/into_variant.hpp[`#include <async/into_variant.hpp>`]
 * xref:sender_factories.adoc#_just[`just`] - https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/just.hpp[`#include <async/just.hpp>`]
 * xref:sender_factories.adoc#_just_error[`just_error`] - https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/just.hpp[`#include <async/just.hpp>`]
 * xref:sender_factories.adoc#_just_error_result_of[`just_error_result_of`] - https://github.com/intel/cpp-baremetal-senders-and-receivers/blob/main/include/async/just_result_of.hpp[`#include <async/just_result_of.hpp>`]
diff --git a/include/async/into_variant.hpp b/include/async/into_variant.hpp
new file mode 100644
index 0000000..b641fc2
--- /dev/null
+++ b/include/async/into_variant.hpp
@@ -0,0 +1,130 @@
+#pragma once
+
+#include <async/completion_tags.hpp>
+#include <async/compose.hpp>
+#include <async/concepts.hpp>
+#include <async/connect.hpp>
+#include <async/debug.hpp>
+#include <async/env.hpp>
+#include <async/type_traits.hpp>
+
+#include <stdx/ct_string.hpp>
+#include <stdx/tuple.hpp>
+#include <stdx/type_traits.hpp>
+
+#include <type_traits>
+#include <utility>
+#include <variant>
+
+namespace async {
+namespace _into_variant {
+template <stdx::ct_string Name, typename S, typename V, typename Rcvr>
+struct receiver {
+    using is_receiver = void;
+    using sender_t = S;
+
+    [[nodiscard]] constexpr auto
+    query(async::get_env_t) const -> forwarding_env<env_of_t<Rcvr>> {
+        return forward_env_of(r);
+    }
+
+    template <typename... Args> auto set_value(Args &&...args) && -> void {
+        debug_signal<set_value_t::name, debug::erased_context_for<receiver>>(
+            get_env(r));
+        std::move(r).set_value(
+            V{stdx::make_tuple(std::forward<Args>(args)...)});
+    }
+
+    template <typename... Args> auto set_error(Args &&...args) && -> void {
+        debug_signal<set_error_t::name, debug::erased_context_for<receiver>>(
+            get_env(r));
+        std::move(r).set_error(std::forward<Args>(args)...);
+    }
+    auto set_stopped() && -> void {
+        debug_signal<set_stopped_t::name, debug::erased_context_for<receiver>>(
+            get_env(r));
+        std::move(r).set_stopped();
+    }
+
+    [[no_unique_address]] Rcvr r;
+};
+
+namespace detail {
+template <typename... As> using discard_signatures = completion_signatures<>;
+
+template <typename... Ts>
+using decayed_tuple = stdx::tuple<std::decay_t<Ts>...>;
+
+template <typename S, typename Env, template <typename...> typename V>
+using variant_t = value_types_of_t<S, Env, decayed_tuple, V>;
+} // namespace detail
+
+template <stdx::ct_string Name, typename S, template <typename...> typename V>
+struct sender {
+    using is_sender = void;
+
+    template <async::receiver R>
+    [[nodiscard]] constexpr auto connect(R &&r) && {
+        check_connect<sender &&, R>();
+        using env_t = env_of_t<std::remove_cvref_t<R>>;
+        using variant_t = detail::variant_t<S, env_t, V>;
+        return async::connect(
+            std::move(s), receiver<Name, S, variant_t, std::remove_cvref_t<R>>{
+                              std::forward<R>(r)});
+    }
+
+    template <async::receiver R>
+        requires multishot_sender<S>
+    [[nodiscard]] constexpr auto connect(R &&r) const & {
+        check_connect<sender const &, R>();
+        using env_t = env_of_t<std::remove_cvref_t<R>>;
+        using variant_t = detail::variant_t<S, env_t, V>;
+        return async::connect(
+            s, receiver<Name, S, variant_t, std::remove_cvref_t<R>>{
+                   std::forward<R>(r)});
+    }
+
+    template <typename Env>
+    [[nodiscard]] constexpr static auto get_completion_signatures(Env const &) {
+        using variant_t = detail::variant_t<S, Env, V>;
+        return transform_completion_signatures_of<
+            S, Env, completion_signatures<set_value_t(variant_t)>,
+            detail::discard_signatures>{};
+    }
+
+    [[no_unique_address]] S s;
+};
+
+template <stdx::ct_string Name, template <typename...> typename V>
+struct pipeable {
+  private:
+    template <async::sender S, stdx::same_as_unqualified<pipeable> Self>
+    friend constexpr auto operator|(S &&s, Self &&) -> async::sender auto {
+        return sender<Name, std::remove_cvref_t<S>, V>{std::forward<S>(s)};
+    }
+};
+} // namespace _into_variant
+
+template <stdx::ct_string Name = "into_variant",
+          template <typename...> typename V = std::variant>
+[[nodiscard]] constexpr auto into_variant() {
+    return _compose::adaptor<_into_variant::pipeable<Name, V>>{};
+}
+
+template <stdx::ct_string Name = "into_variant",
+          template <typename...> typename V = std::variant, sender S>
+[[nodiscard]] constexpr auto into_variant(S &&s) -> sender auto {
+    return std::forward<S>(s) | into_variant<Name, V>();
+}
+
+struct into_variant_t;
+
+template <stdx::ct_string Name, typename... Ts>
+struct debug::context_for<_into_variant::receiver<Name, Ts...>> {
+    using tag = into_variant_t;
+    constexpr static auto name = Name;
+    using type = _into_variant::receiver<Name, Ts...>;
+    using children = stdx::type_list<debug::erased_context_for<
+        connect_result_t<typename type::sender_t &&, type &&>>>;
+};
+} // namespace async
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index 57ef80a..ecbe94e 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -29,6 +29,7 @@ add_tests(
     freestanding_sync_wait
     hosted_sync_wait
     incite_on
+    into_variant
     just
     just_error
     just_error_result_of
diff --git a/test/into_variant.cpp b/test/into_variant.cpp
new file mode 100644
index 0000000..d0c9a41
--- /dev/null
+++ b/test/into_variant.cpp
@@ -0,0 +1,222 @@
+#include "detail/common.hpp"
+
+#include <async/connect.hpp>
+#include <async/debug.hpp>
+#include <async/into_variant.hpp>
+#include <async/just.hpp>
+#include <async/start.hpp>
+#include <async/then.hpp>
+#include <async/variant_sender.hpp>
+
+#include <stdx/ct_format.hpp>
+#include <stdx/tuple.hpp>
+#include <stdx/utility.hpp>
+
+#include <boost/mp11/list.hpp>
+#include <catch2/catch_test_macros.hpp>
+#include <fmt/format.h>
+
+#include <concepts>
+#include <string>
+#include <type_traits>
+#include <utility>
+#include <variant>
+#include <vector>
+
+TEST_CASE("into_variant advertises what it sends", "[into_variant]") {
+    auto s = async::make_variant_sender(
+        false, [] { return async::just(42); },
+        [] { return async::just(3.14f); });
+    [[maybe_unused]] auto iv = async::into_variant(s);
+    static_assert(
+        async::sender_of<decltype(iv),
+                         async::set_value_t(std::variant<stdx::tuple<int>,
+                                                         stdx::tuple<float>>)>);
+    static_assert(not async::sender_of<decltype(iv), async::set_error_t()>);
+}
+
+TEST_CASE("into_variant advertises errors", "[into_variant]") {
+    auto s = async::make_variant_sender(
+        false, [] { return async::just(42); },
+        [] { return async::just_error(3.14f); });
+    [[maybe_unused]] auto iv = async::into_variant(s);
+    static_assert(
+        async::sender_of<decltype(iv),
+                         async::set_value_t(std::variant<stdx::tuple<int>>)>);
+    static_assert(async::sender_of<decltype(iv), async::set_error_t(float)>);
+}
+
+TEST_CASE("basic operation", "[into_variant]") {
+    int value{};
+    auto s = async::make_variant_sender(
+        false, [] { return async::just(42); },
+        [] { return async::just(3.14f); });
+    auto iv = async::into_variant(s);
+    auto op = async::connect(
+        iv, receiver{[&](auto i) {
+            std::visit(stdx::overload{[&](stdx::tuple<int>) { value = 1; },
+                                      [&](stdx::tuple<float>) { value = 2; }},
+                       i);
+        }});
+    async::start(op);
+    CHECK(value == 2);
+}
+
+TEST_CASE("sending multiple values", "[into_variant]") {
+    int value{};
+    auto s = async::make_variant_sender(
+        false, [] { return async::just(42); },
+        [] { return async::just(3.14f, 17); });
+    auto iv = async::into_variant(s);
+    auto op = async::connect(
+        iv, receiver{[&](auto i) {
+            std::visit(
+                stdx::overload{[&](stdx::tuple<int>) { value = 1; },
+                               [&](stdx::tuple<float, int>) { value = 2; }},
+                i);
+        }});
+    async::start(op);
+    CHECK(value == 2);
+}
+
+TEST_CASE("sending void values", "[into_variant]") {
+    int value{};
+    auto s = async::make_variant_sender(
+        false, [] { return async::just(42); }, [] { return async::just(); });
+    auto iv = async::into_variant(s);
+    auto op = async::connect(
+        iv, receiver{[&](auto i) {
+            std::visit(stdx::overload{[&](stdx::tuple<int>) { value = 1; },
+                                      [&](stdx::tuple<>) { value = 2; }},
+                       i);
+        }});
+    async::start(op);
+    CHECK(value == 2);
+}
+
+TEST_CASE("sending move-only values", "[into_variant]") {
+    int value{};
+    auto s = async::make_variant_sender(
+        false, [] { return async::just(42); },
+        [] { return async::just(move_only{42}); });
+    auto iv = async::into_variant(std::move(s));
+    auto op = async::connect(
+        std::move(iv), receiver{[&](auto i) {
+            std::visit(
+                stdx::overload{[&](stdx::tuple<int>) { value = 1; },
+                               [&](stdx::tuple<move_only<int>>) { value = 2; }},
+                std::move(i));
+        }});
+    async::start(op);
+    CHECK(value == 2);
+}
+
+TEST_CASE("into_variant is pipeable", "[into_variant]") {
+    int value{};
+    auto s = async::make_variant_sender(
+        false, [] { return async::just(42); },
+        [] { return async::just(3.14f); });
+    auto iv = s | async::into_variant();
+    auto op = async::connect(
+        iv, receiver{[&](auto i) {
+            std::visit(stdx::overload{[&](stdx::tuple<int>) { value = 1; },
+                                      [&](stdx::tuple<float>) { value = 2; }},
+                       i);
+        }});
+    async::start(op);
+    CHECK(value == 2);
+}
+
+TEST_CASE("into_variant is adaptor-pipeable", "[into_variant]") {
+    int value{};
+    auto s = async::make_variant_sender(
+        false, [] { return async::just(42); },
+        [] { return async::just(3.14f); });
+
+    auto iv = async::into_variant() | async::then([](auto i) { return i; });
+    auto op = async::connect(
+        s | iv, receiver{[&](auto i) {
+            std::visit(stdx::overload{[&](stdx::tuple<int>) { value = 1; },
+                                      [&](stdx::tuple<float>) { value = 2; }},
+                       i);
+        }});
+    async::start(op);
+    CHECK(value == 2);
+}
+
+namespace {
+template <typename... Ts>
+using alt_variant = std::variant<std::monostate, Ts...>;
+}
+
+TEST_CASE("alternative variant", "[into_variant]") {
+    int value{};
+    auto s = async::make_variant_sender(
+        false, [] { return async::just(42); },
+        [] { return async::just(3.14f); });
+    auto iv = async::into_variant<"alt", alt_variant>(s);
+    auto op = async::connect(
+        iv, receiver{[&](auto i) {
+            CHECK(std::same_as<decltype(i),
+                               std::variant<std::monostate, stdx::tuple<int>,
+                                            stdx::tuple<float>>>);
+            value = 42;
+        }});
+    async::start(op);
+    CHECK(value == 42);
+}
+
+namespace {
+std::vector<std::string> debug_events{};
+
+struct debug_handler {
+    template <stdx::ct_string C, stdx::ct_string S, typename Ctx>
+    constexpr auto signal(auto &&...) {
+        using namespace stdx::literals;
+        if constexpr (std::is_same_v<async::debug::tag_of<Ctx>,
+                                     async::into_variant_t>) {
+            static_assert(not boost::mp11::mp_empty<
+                          async::debug::children_of<Ctx>>::value);
+            debug_events.push_back(
+                fmt::format("{} {} {}", C, async::debug::name_of<Ctx>, S));
+        }
+    }
+};
+} // namespace
+
+template <> inline auto async::injected_debug_handler<> = debug_handler{};
+
+TEST_CASE("into_variant can be debugged with a string", "[into_variant]") {
+    using namespace std::string_literals;
+    debug_events.clear();
+
+    auto s = async::make_variant_sender(
+                 false, [] { return async::just(42); },
+                 [] { return async::just(3.14f); }) |
+             async::into_variant();
+    auto op = async::connect(
+        s, with_env{universal_receiver{},
+                    async::prop{async::get_debug_interface_t{},
+                                async::debug::named_interface<"op">{}}});
+
+    async::start(op);
+    CHECK(debug_events == std::vector{"op into_variant set_value"s});
+}
+
+TEST_CASE("into_variant can be named and debugged with a string",
+          "[into_variant]") {
+    using namespace std::string_literals;
+    debug_events.clear();
+
+    auto s = async::make_variant_sender(
+                 false, [] { return async::just(42); },
+                 [] { return async::just(3.14f); }) |
+             async::into_variant<"iv_name">();
+    auto op = async::connect(
+        s, with_env{universal_receiver{},
+                    async::prop{async::get_debug_interface_t{},
+                                async::debug::named_interface<"op">{}}});
+
+    async::start(op);
+    CHECK(debug_events == std::vector{"op iv_name set_value"s});
+}