Replace void filtering with monostate in when_all to preserve index mapping (#204)

Author: mvandeberg

doc/modules/ROOT/pages/4.coroutines/4f.composition.adoc

@@ -58,9 +58,9 @@ task<> example()
 
 `when_all` returns a tuple of results in the same order as the input tasks. Use structured bindings to unpack them.
 
-=== Void Filtering
+=== Void Tasks
 
-Tasks returning `void` do not contribute to the result tuple:
+Tasks returning `void` contribute `std::monostate` to the result tuple, preserving the task-index-to-result-index mapping:
 
 [source,cpp]
 ----
@@ -69,18 +69,21 @@ task<int> int_task() { co_return 42; }
 
 task<> example()
 {
-    auto [value] = co_await when_all(void_task(), int_task(), void_task());
-    // value == 42  (only the int_task contributes)
+    auto [a, b, c] = co_await when_all(int_task(), void_task(), int_task());
+    // a == 42       (int,        index 0)
+    // b == monostate (monostate, index 1)
+    // c == 42       (int,        index 2)
 }
 ----
 
-If all tasks return `void`, `when_all` returns `void`:
+If all tasks return `void`, `when_all` returns a tuple of `std::monostate`:
 
 [source,cpp]
 ----
 task<> example()
 {
-    co_await when_all(void_task_a(), void_task_b());  // Returns void
+    auto [a, b] = co_await when_all(void_task_a(), void_task_b());
+    // a and b are std::monostate
 }
 ----
 

doc/unlisted/coroutines-when-all.adoc

@@ -56,7 +56,7 @@ one finishes.
 
 == Return Value
 
-`when_all` returns a tuple of results, with void types filtered out:
+`when_all` returns a tuple of results. Void tasks contribute `std::monostate` to preserve the task-index-to-result-index mapping:
 
 [source,cpp]
 ----
@@ -67,20 +67,20 @@ auto [x, y] = co_await when_all(
 );
 // x is int, y is std::string
 
-// Mixed with void: void tasks don't contribute
-auto [value] = co_await when_all(
-    task_returning_int(),  // task<int>
-    task_void(),           // task<void> - no contribution
-    task_void()            // task<void> - no contribution
+// Mixed with void: void tasks contribute monostate
+auto [a, b, c] = co_await when_all(
+    task_returning_int(),  // task<int>       — index 0
+    task_void(),           // task<void>      — index 1 → monostate
+    task_void()            // task<void>      — index 2 → monostate
 );
-// value is int (only non-void result)
+// a is int, b and c are std::monostate
 
-// All void: returns void
-co_await when_all(
+// All void: returns tuple of monostate
+auto [m, n] = co_await when_all(
     task_void(),
     task_void()
 );
-// No tuple, no return value
+// m and n are std::monostate
 ----
 
 Results appear in the same order as the input tasks.
@@ -255,7 +255,7 @@ Do NOT use `when_all` when:
 | Launch tasks concurrently, wait for all
 
 | Return type
-| Tuple of non-void results in input order
+| Tuple of results in input order (`monostate` for void tasks)
 
 | Error handling
 | First exception propagated, siblings get stop

doc/unlisted/library-when-all.adoc

@@ -54,7 +54,7 @@ one finishes.
 
 == Return Value
 
-`when_all` returns a tuple of results, with void types filtered out:
+`when_all` returns a tuple of results. Void tasks contribute `std::monostate` to preserve the task-index-to-result-index mapping:
 
 [source,cpp]
 ----
@@ -65,20 +65,20 @@ auto [x, y] = co_await when_all(
 );
 // x is int, y is std::string
 
-// Mixed: void tasks don't contribute
-auto [value] = co_await when_all(
-    returns_int(),  // task<int>
-    returns_void(), // task<void> — no contribution
-    returns_void()  // task<void> — no contribution
+// Mixed: void tasks contribute monostate
+auto [a, b, c] = co_await when_all(
+    returns_int(),  // task<int>       — index 0
+    returns_void(), // task<void>      — index 1 → monostate
+    returns_void()  // task<void>      — index 2 → monostate
 );
-// value is int (only non-void result)
+// a is int, b and c are std::monostate
 
-// All void: returns void
-co_await when_all(
+// All void: returns tuple of monostate
+auto [m, n] = co_await when_all(
     task_void_1(),
     task_void_2()
 );
-// No tuple, no return value
+// m and n are std::monostate
 ----
 
 Results appear in the same order as input tasks.
@@ -244,7 +244,7 @@ task<void> fetch_all(http_client& client)
 | Launch tasks concurrently, wait for all
 
 | Return type
-| Tuple of non-void results in input order
+| Tuple of results in input order (`monostate` for void tasks)
 
 | Error handling
 | First exception propagated, siblings get stop

example/parallel-fetch/parallel_fetch.cpp

@@ -81,13 +81,12 @@ capy::task<std::string> fetch_with_side_effects()
 {
     std::cout << "\n=== Fetch with side effects ===\n";
 
-    // void tasks don't contribute to result tuple
-    std::tuple<std::string> results = co_await capy::when_all(
-        log_access("api/data"),           // void - no result
-        update_metrics("api_calls"),      // void - no result
+    // void tasks contribute monostate to preserve index mapping
+    auto [log, metrics, data] = co_await capy::when_all(
+        log_access("api/data"),           // void → monostate
+        update_metrics("api_calls"),      // void → monostate
         fetch_user_name(42)               // returns string
     );
-    std::string data = std::get<0>(results);  // std::string
 
     std::cout << "Data: " << data << "\n";
     co_return data;

include/boost/capy/detail/void_to_monostate.hpp

@@ -0,0 +1,32 @@
+//
+// Copyright (c) 2026 Michael Vandeberg
+//
+// 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)
+//
+// Official repository: https://github.com/cppalliance/capy
+//
+
+#ifndef BOOST_CAPY_DETAIL_VOID_TO_MONOSTATE_HPP
+#define BOOST_CAPY_DETAIL_VOID_TO_MONOSTATE_HPP
+
+#include <type_traits>
+#include <variant>
+
+namespace boost {
+namespace capy {
+
+/** Map void to std::monostate, pass other types through unchanged.
+
+    std::variant<void, ...> and std::tuple members of type void are
+    ill-formed, so void-returning tasks contribute std::monostate
+    instead. This preserves task-index-to-result-index mapping in
+    both when_all and when_any.
+*/
+template<typename T>
+using void_to_monostate_t = std::conditional_t<std::is_void_v<T>, std::monostate, T>;
+
+} // namespace capy
+} // namespace boost
+
+#endif

include/boost/capy/when_all.hpp

@@ -11,6 +11,7 @@
 #define BOOST_CAPY_WHEN_ALL_HPP
 
 #include <boost/capy/detail/config.hpp>
+#include <boost/capy/detail/void_to_monostate.hpp>
 #include <boost/capy/concept/executor.hpp>
 #include <boost/capy/concept/io_awaitable.hpp>
 #include <coroutine>
@@ -32,19 +33,6 @@ namespace capy {
 
 namespace detail {
 
-/** Type trait to filter void types from a tuple.
-
-    Void-returning tasks do not contribute a value to the result tuple.
-    This trait computes the filtered result type.
-
-    Example: filter_void_tuple_t<int, void, string> = tuple<int, string>
-*/
-template<typename T>
-using wrap_non_void_t = std::conditional_t<std::is_void_v<T>, std::tuple<>, std::tuple<T>>;
-
-template<typename... Ts>
-using filter_void_tuple_t = decltype(std::tuple_cat(std::declval<wrap_non_void_t<Ts>>()...));
-
 /** Holds the result of a single task within when_all.
 */
 template<typename T>
@@ -63,11 +51,12 @@ struct result_holder
     }
 };
 
-/** Specialization for void tasks - no value storage needed.
+/** Specialization for void tasks - returns monostate to preserve index mapping.
 */
 template<>
 struct result_holder<void>
 {
+    std::monostate get() && { return {}; }
 };
 
 /** Shared state for when_all operation.
@@ -358,45 +347,38 @@ class when_all_launcher
     }
 };
 
-/** Helper to extract a single result, returning empty tuple for void.
+/** Helper to extract a single result from state.
     This is a separate function to work around a GCC-11 ICE that occurs
     when using nested immediately-invoked lambdas with pack expansion.
 */
 template<std::size_t I, typename... Ts>
 auto extract_single_result(when_all_state<Ts...>& state)
 {
-    using T = std::tuple_element_t<I, std::tuple<Ts...>>;
-    if constexpr (std::is_void_v<T>)
-        return std::tuple<>();
-    else
-        return std::make_tuple(std::move(std::get<I>(state.results_)).get());
+    return std::move(std::get<I>(state.results_)).get();
 }
 
-/** Extract results from state, filtering void types.
+/** Extract all results from state as a tuple.
 */
 template<typename... Ts>
 auto extract_results(when_all_state<Ts...>& state)
 {
     return [&]<std::size_t... Is>(std::index_sequence<Is...>) {
-        return std::tuple_cat(extract_single_result<Is>(state)...);
+        return std::tuple(extract_single_result<Is>(state)...);
     }(std::index_sequence_for<Ts...>{});
 }
 
 } // namespace detail
 
-/** Compute a tuple type with void types filtered out.
+/** Compute the when_all result tuple type.
 
-    Returns void when all types are void (P2300 aligned),
-    otherwise returns a std::tuple with void types removed.
+    Void-returning tasks contribute std::monostate to preserve the
+    task-index-to-result-index mapping, matching when_any's approach.
 
-    Example: non_void_tuple_t<int, void, string> = std::tuple<int, string>
-    Example: non_void_tuple_t<void, void> = void
+    Example: when_all_result_t<int, void, string> = std::tuple<int, std::monostate, string>
+    Example: when_all_result_t<void, void> = std::tuple<std::monostate, std::monostate>
 */
 template<typename... Ts>
-using non_void_tuple_t = std::conditional_t<
-    std::is_same_v<detail::filter_void_tuple_t<Ts...>, std::tuple<>>,
-    void,
-    detail::filter_void_tuple_t<Ts...>>;
+using when_all_result_t = std::tuple<void_to_monostate_t<Ts>...>;
 
 /** Execute multiple awaitables concurrently and collect their results.
 
@@ -407,8 +389,8 @@ using non_void_tuple_t = std::conditional_t<
 
     @li All child awaitables run concurrently on the caller's executor
     @li Results are returned as a tuple in input order
-    @li Void-returning awaitables do not contribute to the result tuple
-    @li If all awaitables return void, `when_all` returns `task<void>`
+    @li Void-returning awaitables contribute std::monostate to the
+        result tuple, preserving the task-index-to-result-index mapping
     @li First exception wins; subsequent exceptions are discarded
     @li Stop is requested for siblings on first error
     @li Completes only after all children have finished
@@ -422,8 +404,8 @@ using non_void_tuple_t = std::conditional_t<
         satisfy @ref IoAwaitable and is consumed (moved-from) when
         `when_all` is awaited.
 
-    @return A task yielding a tuple of non-void results. Returns
-        `task<void>` when all input awaitables return void.
+    @return A task yielding a tuple of results in input order. Void tasks
+        contribute std::monostate to preserve index correspondence.
 
     @par Example
 
@@ -436,23 +418,22 @@ using non_void_tuple_t = std::conditional_t<
             fetch_posts( id )      // task<std::vector<Post>>
         );
 
-        // Void awaitables don't contribute to result
-        co_await when_all(
-            log_event( "start" ),  // task<void>
-            notify_user( id )      // task<void>
+        // Void awaitables contribute monostate
+        auto [a, _, b] = co_await when_all(
+            fetch_int(),           // task<int>
+            log_event( "start" ),  // task<void>  → monostate
+            fetch_str()            // task<string>
         );
-        // Returns task<void>, no result tuple
+        // a is int, _ is monostate, b is string
     }
     @endcode
 
     @see IoAwaitable, task
 */
 template<IoAwaitable... As>
 [[nodiscard]] auto when_all(As... awaitables)
-    -> task<non_void_tuple_t<awaitable_result_t<As>...>>
+    -> task<when_all_result_t<awaitable_result_t<As>...>>
 {
-    using result_type = non_void_tuple_t<awaitable_result_t<As>...>;
-
     // State is stored in the coroutine frame, using the frame allocator
     detail::when_all_state<awaitable_result_t<As>...> state;
 
@@ -469,11 +450,7 @@ template<IoAwaitable... As>
     if(state.first_exception_)
         std::rethrow_exception(state.first_exception_);
 
-    // Extract and return results
-    if constexpr (std::is_void_v<result_type>)
-        co_return;
-    else
-        co_return detail::extract_results(state);
+    co_return detail::extract_results(state);
 }
 
 } // namespace capy

include/boost/capy/when_any.hpp

@@ -11,6 +11,7 @@
 #define BOOST_CAPY_WHEN_ANY_HPP
 
 #include <boost/capy/detail/config.hpp>
+#include <boost/capy/detail/void_to_monostate.hpp>
 #include <boost/capy/concept/executor.hpp>
 #include <boost/capy/concept/io_awaitable.hpp>
 #include <coroutine>
@@ -115,17 +116,6 @@
 namespace boost {
 namespace capy {
 
-/** Convert void to monostate for variant storage.
-
-    std::variant<void, ...> is ill-formed, so void tasks contribute
-    std::monostate to the result variant instead. Non-void types
-    pass through unchanged.
-
-    @tparam T The type to potentially convert (void becomes monostate).
-*/
-template<typename T>
-using void_to_monostate_t = std::conditional_t<std::is_void_v<T>, std::monostate, T>;
-
 namespace detail {
 
 /** Core shared state for when_any operations.