From da9b280f602ac53c84807164b44fbc9835304127 Mon Sep 17 00:00:00 2001
From: tzcnt <trailingzerocount@gmail.com>
Date: Sat, 27 Jun 2026 09:33:06 -0700
Subject: [PATCH 1/2] comments / formatting only

---
 include/tmc/detail/concepts_awaitable.hpp |  28 +++--
 include/tmc/spawn_tuple.hpp               | 132 ++++++++--------------
 2 files changed, 63 insertions(+), 97 deletions(-)

diff --git a/include/tmc/detail/concepts_awaitable.hpp b/include/tmc/detail/concepts_awaitable.hpp
index 50e857d1..64626b77 100644
--- a/include/tmc/detail/concepts_awaitable.hpp
+++ b/include/tmc/detail/concepts_awaitable.hpp
@@ -21,8 +21,7 @@ template <typename T> struct await_resume_t_impl {
   using type = unknown_t;
 };
 template <AwaitResumeIsWellFormed T> struct await_resume_t_impl<T> {
-  using type =
-    std::remove_reference_t<decltype(std::declval<T&>().await_resume())>;
+  using type = std::remove_reference_t<decltype(std::declval<T&>().await_resume())>;
 };
 /// end await_resume_t_impl<T>
 
@@ -39,9 +38,7 @@ template <NonVoid Awaitable> struct unknown_awaitable_traits<Awaitable> {
   template <typename T> static decltype(auto) guess_awaiter(T&& value) {
     if constexpr (requires { static_cast<T&&>(value).operator co_await(); }) {
       return static_cast<T&&>(value).operator co_await();
-    } else if constexpr (requires {
-                           operator co_await(static_cast<T&&>(value));
-                         }) {
+    } else if constexpr (requires { operator co_await(static_cast<T&&>(value)); }) {
       return operator co_await(static_cast<T&&>(value));
     } else {
       return static_cast<T&&>(value);
@@ -97,6 +94,9 @@ using result_type = typename (result type of `co_await YourAwaitable;`);
 // Implementing this is OPTIONAL; if unimplemented, each awaitable will be
 // wrapped in a task that will automagically restore its executor and priority
 // before returning, thus preventing errors out-of-the-box.
+//
+// Setting the reference category of self_type (& or &&) controls whether this is an
+rvalue-only or lvalue-only awaitable.
 
 static awaiter_type get_awaiter(self_type& Awaitable) {
   return awaiter_type(Awaitable);
@@ -116,6 +116,9 @@ static constexpr configure_mode mode = COROUTINE;
 // If set to ASYNC_INITIATE, you must define this function, which will be
 // called to initiate the async process. The current TMC executor and priority
 // will be passed in, but they are not required to be used.
+//
+// Setting the reference category of Awaitable (& or &&) controls whether this is an
+rvalue-only or lvalue-only awaitable.
 
 static constexpr configure_mode mode = ASYNC_INITIATE;
 static void async_initiate(
@@ -147,8 +150,7 @@ static void set_flags(Awaitable& YourAwaitable, size_t Flags);
 
 */
 template <typename Awaitable>
-using get_awaitable_traits =
-  awaitable_traits<std::remove_reference_t<Awaitable>>;
+using get_awaitable_traits = awaitable_traits<std::remove_reference_t<Awaitable>>;
 
 template <typename Awaitable>
 using awaitable_result_t =
@@ -185,11 +187,9 @@ template <HasAwaitTagNoGroupAsIs Awaitable> struct awaitable_traits<Awaitable> {
 struct AwaitTagNoGroupCoAwait {};
 
 template <typename T>
-concept HasAwaitTagNoGroupCoAwait =
-  std::is_base_of_v<AwaitTagNoGroupCoAwait, T>;
+concept HasAwaitTagNoGroupCoAwait = std::is_base_of_v<AwaitTagNoGroupCoAwait, T>;
 
-template <HasAwaitTagNoGroupCoAwait Awaitable>
-struct awaitable_traits<Awaitable> {
+template <HasAwaitTagNoGroupCoAwait Awaitable> struct awaitable_traits<Awaitable> {
   static constexpr configure_mode mode = WRAPPER;
 
   static decltype(auto) get_awaiter(Awaitable&& awaitable) noexcept {
@@ -211,8 +211,7 @@ template <typename T>
 concept HasAwaitTagNoGroupCoAwaitLvalue =
   std::is_base_of_v<AwaitTagNoGroupCoAwaitLvalue, T>;
 
-template <HasAwaitTagNoGroupCoAwaitLvalue Awaitable>
-struct awaitable_traits<Awaitable> {
+template <HasAwaitTagNoGroupCoAwaitLvalue Awaitable> struct awaitable_traits<Awaitable> {
   static constexpr configure_mode mode = WRAPPER;
 
   static decltype(auto) get_awaiter(Awaitable& awaitable) noexcept {
@@ -247,8 +246,7 @@ template <IsRange R> struct range_iter {
 /// Given T&& -> holds T&& if T is not move-constructible
 template <typename T>
 using forward_awaitable = std::conditional_t<
-  std::is_rvalue_reference_v<T&&> &&
-    std::is_move_constructible_v<std::decay_t<T>>,
+  std::is_rvalue_reference_v<T&&> && std::is_move_constructible_v<std::decay_t<T>>,
   std::decay_t<T>, T&&>;
 
 /// Must be defined by each TMC executor. No default implementation is provided.
diff --git a/include/tmc/spawn_tuple.hpp b/include/tmc/spawn_tuple.hpp
index b7019c40..7d8bd120 100644
--- a/include/tmc/spawn_tuple.hpp
+++ b/include/tmc/spawn_tuple.hpp
@@ -26,8 +26,7 @@ namespace tmc {
 namespace detail {
 // Replace void with std::monostate (void is not a valid tuple element type)
 template <typename T>
-using void_to_monostate =
-  std::conditional_t<std::is_void_v<T>, std::monostate, T>;
+using void_to_monostate = std::conditional_t<std::is_void_v<T>, std::monostate, T>;
 
 // Get the last type of a parameter pack
 // In C++26 you can use pack indexing instead: T...[sizeof...(T) - 1]
@@ -44,9 +43,7 @@ template <typename... T> using last_type_t = typename last_type<T...>::type;
 
 // Create 2 instantiations of the Variadic, one where all of the types
 // satisfy the predicate, and one where none of the types satisfy the predicate.
-template <
-  template <class> class Predicate, template <class...> class Variadic,
-  class...>
+template <template <class> class Predicate, template <class...> class Variadic, class...>
 struct predicate_partition;
 
 // Definition for empty parameter pack
@@ -69,18 +66,15 @@ struct predicate_partition<Predicate, Variadic, T, Ts...> {
   using true_types = typename std::conditional<
     Predicate<T>::value,
     typename Cons<
-      T, typename predicate_partition<Predicate, Variadic, Ts...>::true_types>::
-      type,
+      T, typename predicate_partition<Predicate, Variadic, Ts...>::true_types>::type,
     typename predicate_partition<Predicate, Variadic, Ts...>::true_types>::type;
 
   // No type in the parameter pack satisfies the predicate
   using false_types = typename std::conditional<
     !Predicate<T>::value,
     typename Cons<
-      T, typename predicate_partition<
-           Predicate, Variadic, Ts...>::false_types>::type,
-    typename predicate_partition<Predicate, Variadic, Ts...>::false_types>::
-    type;
+      T, typename predicate_partition<Predicate, Variadic, Ts...>::false_types>::type,
+    typename predicate_partition<Predicate, Variadic, Ts...>::false_types>::type;
 };
 
 // Partition the awaitables into two groups:
@@ -104,10 +98,11 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
   static constexpr auto Count = sizeof...(Awaitable);
 
   // When result_each() is called, tasks are synchronized via an atomic bitmask
-  // with only 63 (or 31, on 32-bit) slots for tasks. result_each() doesn't seem
-  // like a good fit for larger task groups anyway. If you really need more
-  // room, please open a GitHub issue explaining why...
-  static_assert(!IsEach || Count < TMC_PLATFORM_BITS);
+  // with only 63 (or 31, on 32-bit) slots for tasks.
+  static_assert(
+    !IsEach || Count < TMC_PLATFORM_BITS,
+    "result_each() supports at most 63 awaitables (31 on 32-bit platforms)."
+  );
 
   static constexpr size_t WorkItemCount =
     std::tuple_size_v<typename tmc::detail::predicate_partition<
@@ -125,9 +120,8 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
     sync_flags_or_done_count;
 
   template <typename T>
-  using ResultStorage =
-    tmc::detail::result_storage_t<tmc::detail::void_to_monostate<
-      typename tmc::detail::get_awaitable_traits<T>::result_type>>;
+  using ResultStorage = tmc::detail::result_storage_t<tmc::detail::void_to_monostate<
+    typename tmc::detail::get_awaitable_traits<T>::result_type>>;
   using ResultTuple = std::tuple<ResultStorage<Awaitable>...>;
   ResultTuple result;
 
@@ -145,18 +139,15 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
     tmc::detail::get_awaitable_traits<T>::set_continuation_executor(
       Task, &continuation_executor
     );
-    tmc::detail::get_awaitable_traits<T>::set_done_count(
-      Task, &sync_flags_or_done_count
-    );
+    tmc::detail::get_awaitable_traits<T>::set_done_count(Task, &sync_flags_or_done_count);
     if constexpr (IsEach) {
       tmc::detail::get_awaitable_traits<T>::set_flags(
         Task, tmc::detail::task_flags::EACH |
-                (Idx << tmc::detail::task_flags::TASKNUM_LOW_OFF) |
-                ContinuationPrio
+                (Idx << tmc::detail::task_flags::TASKNUM_LOW_OFF) | ContinuationPrio
       );
     }
-    if constexpr (!std::is_void_v<typename tmc::detail::get_awaitable_traits<
-                    T>::result_type>) {
+    if constexpr (!std::is_void_v<
+                    typename tmc::detail::get_awaitable_traits<T>::result_type>) {
       tmc::detail::get_awaitable_traits<T>::set_result_ptr(Task, TaskResult);
     }
 
@@ -176,18 +167,15 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
     tmc::detail::get_awaitable_traits<T>::set_continuation_executor(
       Task, &continuation_executor
     );
-    tmc::detail::get_awaitable_traits<T>::set_done_count(
-      Task, &sync_flags_or_done_count
-    );
+    tmc::detail::get_awaitable_traits<T>::set_done_count(Task, &sync_flags_or_done_count);
     if constexpr (IsEach) {
       tmc::detail::get_awaitable_traits<T>::set_flags(
         Task, tmc::detail::task_flags::EACH |
-                (Idx << tmc::detail::task_flags::TASKNUM_LOW_OFF) |
-                ContinuationPrio
+                (Idx << tmc::detail::task_flags::TASKNUM_LOW_OFF) | ContinuationPrio
       );
     }
-    if constexpr (!std::is_void_v<typename tmc::detail::get_awaitable_traits<
-                    T>::result_type>) {
+    if constexpr (!std::is_void_v<
+                    typename tmc::detail::get_awaitable_traits<T>::result_type>) {
       tmc::detail::get_awaitable_traits<T>::set_result_ptr(Task, TaskResult);
     }
   }
@@ -206,8 +194,8 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
   }
 
   aw_spawn_tuple_impl(
-    AwaitableTuple&& Tasks, tmc::ex_any* Executor,
-    tmc::ex_any* ContinuationExecutor, size_t Prio, bool DoSymmetricTransfer
+    AwaitableTuple&& Tasks, tmc::ex_any* Executor, tmc::ex_any* ContinuationExecutor,
+    size_t Prio, bool DoSymmetricTransfer
   )
       : continuation_executor{ContinuationExecutor} {
     if constexpr (!IsEach) {
@@ -226,13 +214,13 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
          constexpr auto mode = tmc::detail::get_awaitable_traits<
            std::tuple_element_t<I, AwaitableTuple>>::mode;
          static_assert(
-           mode != tmc::detail::UNKNOWN,
-           "This doesn't appear to be an awaitable."
+           mode != tmc::detail::UNKNOWN, "This doesn't appear to be an awaitable."
          );
          if constexpr (mode == tmc::detail::ASYNC_INITIATE) {
+           // The std::move is a bit misleading here - this actually forwards the
+           // awaitable from within the tuple with its original value category.
            prepare_awaitable(
-             std::get<I>(std::move(Tasks)), &std::get<I>(result), I,
-             continuationPriority
+             std::get<I>(std::move(Tasks)), &std::get<I>(result), I, continuationPriority
            );
          } else {
            prepare_task(
@@ -268,8 +256,9 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
       (([&]() {
          if constexpr (!tmc::detail::treat_as_coroutine<
                          std::tuple_element_t<I, AwaitableTuple>>::value) {
-           tmc::detail::get_awaitable_traits<
-             std::tuple_element_t<I, AwaitableTuple>>::
+           // The std::move is a bit misleading here - this actually forwards the
+           // awaitable from within the tuple with its original value category.
+           tmc::detail::get_awaitable_traits<std::tuple_element_t<I, AwaitableTuple>>::
              async_initiate(std::get<I>(std::move(Tasks)), Executor, Prio);
          }
        }()),
@@ -289,14 +278,11 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
 
   /// Suspends the outer coroutine, submits the wrapped task to the
   /// executor, and waits for it to complete.
-  inline std::coroutine_handle<>
-  await_suspend(std::coroutine_handle<> Outer) noexcept
+  inline std::coroutine_handle<> await_suspend(std::coroutine_handle<> Outer) noexcept
     requires(!IsEach)
   {
 #ifndef NDEBUG
-    assert(
-      sync_flags_or_done_count.load() >= 0 && "You may only co_await this once."
-    );
+    assert(sync_flags_or_done_count.load() >= 0 && "You may only co_await this once.");
 #endif
     continuation = Outer;
     std::coroutine_handle<> next;
@@ -307,8 +293,7 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
       // This logic is necessary because we submitted all child tasks before the
       // parent suspended. Allowing parent to be resumed before it suspends
       // would be UB. Therefore we need to block the resumption until here.
-      auto remaining =
-        sync_flags_or_done_count.fetch_sub(1, std::memory_order_acq_rel);
+      auto remaining = sync_flags_or_done_count.fetch_sub(1, std::memory_order_acq_rel);
       // No symmetric transfer - all tasks were already posted.
       // Suspend if remaining > 0 (task is still running)
       if (remaining > 0) {
@@ -356,8 +341,8 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
     requires(IsEach)
   {
     return tmc::detail::result_each_await_suspend(
-      remaining_count_or_symmetric_task, Outer, continuation,
-      continuation_executor, sync_flags_or_done_count
+      remaining_count_or_symmetric_task, Outer, continuation, continuation_executor,
+      sync_flags_or_done_count
     );
   }
 
@@ -394,14 +379,10 @@ template <bool IsEach, typename... Awaitable> class aw_spawn_tuple_impl {
   ~aw_spawn_tuple_impl() noexcept {
     if constexpr (IsEach) {
       assert(
-        remaining_count_or_symmetric_task == 0 &&
-        "You must submit or co_await this."
+        remaining_count_or_symmetric_task == 0 && "You must submit or co_await this."
       );
     } else {
-      assert(
-        sync_flags_or_done_count.load() < 0 &&
-        "You must submit or co_await this."
-      );
+      assert(sync_flags_or_done_count.load() < 0 && "You must submit or co_await this.");
     }
   }
 #endif
@@ -466,8 +447,7 @@ class [[nodiscard(
 
   /// Initiates all of the wrapped tasks and waits for them to complete.
   aw_spawn_tuple_impl<false, Awaitable...> operator co_await() && noexcept {
-    bool doSymmetricTransfer =
-      tmc::detail::this_thread::exec_prio_is(executor, prio);
+    bool doSymmetricTransfer = tmc::detail::this_thread::exec_prio_is(executor, prio);
 #ifndef NDEBUG
     if constexpr (Count != 0) {
       // Ensure that this was not previously moved-from
@@ -476,8 +456,7 @@ class [[nodiscard(
     is_empty = true;
 #endif
     return aw_spawn_tuple_impl<false, Awaitable...>(
-      std::move(wrapped), executor, continuation_executor, prio,
-      doSymmetricTransfer
+      std::move(wrapped), executor, continuation_executor, prio, doSymmetricTransfer
     );
   }
 
@@ -494,8 +473,7 @@ class [[nodiscard(
   aw_spawn_tuple& operator=(const aw_spawn_tuple&) = delete;
   aw_spawn_tuple(aw_spawn_tuple&& Other)
       : wrapped(std::move(Other.wrapped)), executor(std::move(Other.executor)),
-        continuation_executor(std::move(Other.continuation_executor)),
-        prio(Other.prio) {
+        continuation_executor(std::move(Other.continuation_executor)), prio(Other.prio) {
 #if !defined(NDEBUG)
     is_empty = Other.is_empty;
     Other.is_empty = true;
@@ -530,8 +508,9 @@ class [[nodiscard(
          if constexpr (tmc::detail::get_awaitable_traits<
                          std::tuple_element_t<I, AwaitableTuple>>::mode ==
                        tmc::detail::ASYNC_INITIATE) {
-           tmc::detail::get_awaitable_traits<
-             std::tuple_element_t<I, AwaitableTuple>>::
+           // The std::move is a bit misleading here - this actually forwards the
+           // awaitable from within the tuple with its original value category.
+           tmc::detail::get_awaitable_traits<std::tuple_element_t<I, AwaitableTuple>>::
              async_initiate(std::get<I>(std::move(wrapped)), executor, prio);
          } else {
            taskArr[taskIdx] = tmc::detail::into_initiate(
@@ -550,9 +529,7 @@ class [[nodiscard(
     }
     is_empty = true;
 #endif
-    tmc::detail::post_bulk_checked(
-      executor, taskArr.data(), WorkItemCount, prio
-    );
+    tmc::detail::post_bulk_checked(executor, taskArr.data(), WorkItemCount, prio);
   }
 
   /// Submits the tasks to the executor immediately, without suspending the
@@ -621,17 +598,15 @@ spawn_tuple(TMC_CORO_AWAIT_ELIDABLE_ARGUMENT Awaitable&&... Awaitables) {
 ///
 /// Does not support non-awaitable types (such as regular functors).
 template <typename... Awaitable>
-aw_spawn_tuple<Awaitable...> spawn_tuple(
-  TMC_CORO_AWAIT_ELIDABLE_ARGUMENT std::tuple<Awaitable...>&& Awaitables
-) {
+aw_spawn_tuple<Awaitable...>
+spawn_tuple(TMC_CORO_AWAIT_ELIDABLE_ARGUMENT std::tuple<Awaitable...>&& Awaitables) {
   return aw_spawn_tuple<Awaitable...>(
     static_cast<std::tuple<Awaitable...>&&>(Awaitables)
   );
 }
 
 namespace detail {
-template <typename... Awaitables>
-struct awaitable_traits<aw_spawn_tuple<Awaitables...>> {
+template <typename... Awaitables> struct awaitable_traits<aw_spawn_tuple<Awaitables...>> {
   static constexpr configure_mode mode = WRAPPER;
 
   using result_type = std::tuple<tmc::detail::void_to_monostate<
@@ -650,8 +625,7 @@ struct awaitable_traits<aw_spawn_tuple<Awaitables...>> {
 /// which will return the real awaitable (that you can await later to join the
 /// forked task).
 template <typename... Awaitable>
-class TMC_CORO_AWAIT_ELIDABLE aw_fork_tuple_clang
-    : tmc::detail::AwaitTagNoGroupAsIs {
+class TMC_CORO_AWAIT_ELIDABLE aw_fork_tuple_clang : tmc::detail::AwaitTagNoGroupAsIs {
   using AwaitableTuple = std::tuple<Awaitable...>;
   AwaitableTuple wrapped;
 
@@ -666,12 +640,8 @@ class TMC_CORO_AWAIT_ELIDABLE aw_fork_tuple_clang
   inline void await_suspend(std::coroutine_handle<>) noexcept {}
 
   /// Returns the value provided by the wrapped function.
-  TMC_AWAIT_RESUME inline aw_spawn_tuple_fork<Awaitable...>
-  await_resume() noexcept {
-    return tmc::spawn_tuple<Awaitable...>(
-             static_cast<AwaitableTuple&&>(wrapped)
-    )
-      .fork();
+  TMC_AWAIT_RESUME inline aw_spawn_tuple_fork<Awaitable...> await_resume() noexcept {
+    return tmc::spawn_tuple<Awaitable...>(static_cast<AwaitableTuple&&>(wrapped)).fork();
   }
 };
 
@@ -691,9 +661,7 @@ class TMC_CORO_AWAIT_ELIDABLE aw_fork_tuple_clang
 /// auto result_tuple = co_await std::move(forked_task_tuple);
 /// ```
 template <typename... Awaitable>
-[[nodiscard(
-  "You must co_await fork_tuple_clang() immediately for HALO to be possible."
-)]]
+[[nodiscard("You must co_await fork_tuple_clang() immediately for HALO to be possible.")]]
 aw_fork_tuple_clang<tmc::detail::forward_awaitable<Awaitable>...>
 fork_tuple_clang(TMC_CORO_AWAIT_ELIDABLE_ARGUMENT Awaitable&&... Awaitables) {
   return aw_fork_tuple_clang<tmc::detail::forward_awaitable<Awaitable>...>(

From ef917cfd3b2d9e44cd63a5ddb5c7fcb8f1dcb666 Mon Sep 17 00:00:00 2001
From: tzcnt <trailingzerocount@gmail.com>
Date: Sat, 27 Jun 2026 13:51:41 -0700
Subject: [PATCH 2/2] add select()

---
 include/tmc/all_headers.hpp |   1 +
 include/tmc/select.hpp      | 330 ++++++++++++++++++++++++++++++++++++
 2 files changed, 331 insertions(+)
 create mode 100644 include/tmc/select.hpp

diff --git a/include/tmc/all_headers.hpp b/include/tmc/all_headers.hpp
index 477dcb27..86936690 100644
--- a/include/tmc/all_headers.hpp
+++ b/include/tmc/all_headers.hpp
@@ -32,6 +32,7 @@
 #include "tmc/qu_spsc_bounded.hpp"    // IWYU pragma: export
 #include "tmc/qu_spsc_unbounded.hpp"  // IWYU pragma: export
 #include "tmc/rw_lock.hpp"            // IWYU pragma: export
+#include "tmc/select.hpp"             // IWYU pragma: export
 #include "tmc/semaphore.hpp"          // IWYU pragma: export
 #include "tmc/spawn.hpp"              // IWYU pragma: export
 #include "tmc/spawn_func.hpp"         // IWYU pragma: export
diff --git a/include/tmc/select.hpp b/include/tmc/select.hpp
new file mode 100644
index 00000000..e3327fab
--- /dev/null
+++ b/include/tmc/select.hpp
@@ -0,0 +1,330 @@
+// Copyright (c) 2023-2026 Logan McDougall
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+#pragma once
+
+#include "tmc/detail/compat.hpp"
+#include "tmc/detail/concepts_awaitable.hpp" // IWYU pragma: keep
+#include "tmc/spawn_tuple.hpp"
+#include "tmc/task.hpp"
+#include "tmc/traits.hpp"
+
+#include <coroutine>
+#include <optional>
+#include <type_traits>
+#include <utility>
+#include <variant>
+
+namespace tmc {
+namespace detail {
+// Marker used as the `Canceller` of a `tmc::cancellable` when the awaitable is
+// its own cancellation handle (the single-argument `tmc::cancellable`
+// constructor). It is empty; with TMC_NO_UNIQUE_ADDRESS on the member, it occupies no
+// storage.
+struct cancel_self_t {};
+
+// A nullary canceller that holds a cancellation target and invokes its
+// `.cancel()` method, forwarding whatever that method returns. `Target` is
+// instantiated as `forward_awaitable<T>`, so the target is owned by value when
+// it was passed as a movable rvalue, and held by reference (lvalue or
+// non-movable rvalue) otherwise. Produced by the object-taking constructor
+// (form 2) of `tmc::cancellable`. The forwarded result lets `select()` detect an
+// awaitable `.cancel()` (an async cancel) and await it.
+template <typename Target> struct cancel_caller {
+  Target target;
+  decltype(auto) operator()() { return target.cancel(); }
+};
+
+// A trivial awaiter used by `select()` only in its async cancel branch for any sync
+// canceller mixed in. The fold expression cannot handle mixed await / no-await, so we
+// must provide an awaitable object for syntactic compatibility.
+struct cancel_noop : tmc::detail::AwaitTagNoGroupAsIs {
+  static constexpr bool await_ready() noexcept { return true; }
+  static void await_suspend(std::coroutine_handle<>) noexcept {}
+  static void await_resume() noexcept {}
+};
+
+// Forward-declared here so `tmc::cancellable` can grant it friendship.
+template <typename Awaitable, typename Canceller> consteval bool canceller_is_async();
+
+} // namespace detail
+
+/// Pairs an `Awaitable` with a `Canceller` for use with `tmc::select()`.
+///
+/// Construct one with class template argument deduction - `tmc::cancellable(...)`
+/// selects the correct specialization automatically. Three forms are supported:
+///
+/// 1. `tmc::cancellable(awaitable, canceller)` where `canceller` is a nullary functor
+/// that cancels the operation when invoked. It may return void (a sync cancel) or
+/// an awaitable (an async cancel, which `select()` awaits). The canceller is
+/// stored by value and invoked only for losers, so an awaitable-returning canceller
+/// builds its awaitable only when the cancel is actually needed.
+/// ```
+/// // sync cancel
+/// tmc::cancellable(timer.async_wait(tmc::aw_asio), [&]{ timer.cancel(); })
+///
+/// // async cancel via a functor lazily returning an awaitable
+/// tmc::cancellable(op.async_do(), [&]{ return op.async_cancel(); })
+///
+/// // async cancel via a functor lazily returning a task
+/// tmc::cancellable(op.async_do(), [&]() -> tmc::task<void> {
+///   co_await op.async_cancel();
+/// })
+/// ```
+///
+/// 2. `tmc::cancellable(awaitable, object)` where `object` exposes a `.cancel()` method.
+/// The `.cancel()` method may be sync or async (awaitable).
+/// ```
+/// // sync cancel - timer.cancel() runs syncly (an Asio I/O object)
+/// tmc::cancellable(timer.async_wait(tmc::aw_asio), timer)
+///
+/// // async cancel - op.cancel() returns an awaitable, which select() awaits
+/// tmc::cancellable(op.async_do(), op)
+/// ```
+///
+/// 3. `tmc::cancellable(object)` where `object` is itself both the awaitable and
+/// the cancellation handle: it can be co_awaited and also exposes a `.cancel()`
+/// method. The `.cancel()` method can be sync or async (awaitable); `select()` will
+/// automatically await it if needed. This constructor only accepts lvalues or non-movable
+/// rvalues. Movable rvalues are rejected to prevent lifetime issues.
+/// ```
+/// // sync cancel - op.cancel() runs syncly
+/// tmc::cancellable(op)
+///
+/// // async cancel - op2.cancel() returns an awaitable, which select() awaits
+/// tmc::cancellable(op2)
+/// ```
+///
+/// In every form, the cancellation action must be safe to run even
+/// after the operation has already completed (it may race with completion) and
+/// should not throw. `select()` runs the canceller of each losing awaitable
+/// exactly once.
+///
+/// Value category is forwarded throughout: a movable rvalue is owned by value;
+/// an lvalue or non-movable rvalue is borrowed (held by reference) and must
+/// outlive the `tmc::select()` call. Constructor CTAD handles this automatically.
+template <typename Awaitable, typename Canceller> class cancellable {
+  Awaitable awaitable;
+  // Empty cancellers (a captureless lambda, or `cancel_self_t`) cost no storage.
+  TMC_NO_UNIQUE_ADDRESS Canceller canceller;
+
+  template <typename... A, typename... C>
+  friend tmc::task<std::variant<tmc::detail::void_to_monostate<
+    typename tmc::detail::get_awaitable_traits<A>::result_type>...>>
+  select(tmc::cancellable<A, C>... Pairs);
+
+  template <typename A, typename C>
+  friend consteval bool tmc::detail::canceller_is_async();
+
+public:
+  /// `tmc::cancellable(awaitable, canceller)` where `canceller` is a nullary functor
+  /// that cancels the operation when invoked. It may return void (a sync cancel)
+  /// or an awaitable (an async cancel, which `select()` awaits). The canceller is
+  /// stored by value and invoked only for losers, so an awaitable-returning canceller
+  /// builds its awaitable only when the cancel is actually needed.
+  /// ```
+  /// // sync cancel
+  /// tmc::cancellable(timer.async_wait(tmc::aw_asio), [&]{ timer.cancel(); })
+  ///
+  /// // async cancel via a functor lazily returning an awaitable
+  /// tmc::cancellable(op.async_do(), [&]{ return op.async_cancel(); })
+  ///
+  /// // async cancel via a functor lazily returning a task
+  /// tmc::cancellable(op.async_do(), [&]() -> tmc::task<void> {
+  ///   co_await op.async_cancel();
+  /// })
+  /// ```
+  template <typename A, typename C>
+    requires(tmc::traits::executable_kind_v<std::decay_t<C>> ==
+             tmc::traits::executable_kind::CALLABLE)
+  cancellable(A&& Aw, C&& Cancel)
+      : awaitable(static_cast<A&&>(Aw)), canceller(static_cast<C&&>(Cancel)) {}
+
+  /// `tmc::cancellable(awaitable, object)` where `object` exposes a `.cancel()`
+  /// method. The `.cancel()` method may be sync or async (awaitable).
+  /// ```
+  /// // sync cancel - timer.cancel() runs syncly (an Asio I/O object)
+  /// tmc::cancellable(timer.async_wait(tmc::aw_asio), timer)
+  ///
+  /// // async cancel - op.cancel() returns an awaitable, which select() awaits
+  /// tmc::cancellable(op.async_do(), op)
+  template <typename A, typename C>
+    requires(tmc::traits::executable_kind_v<std::decay_t<C>> ==
+               tmc::traits::executable_kind::UNKNOWN &&
+             requires(C& Obj) { Obj.cancel(); })
+  cancellable(A&& Aw, C&& Obj)
+      : awaitable(static_cast<A&&>(Aw)), canceller{static_cast<C&&>(Obj)} {}
+
+  /// `tmc::cancellable(object)` where `object` is itself both the awaitable and
+  /// the cancellation handle: it can be co_awaited and also exposes a `.cancel()`
+  /// method. The `.cancel()` method can be sync or async (awaitable); `select()` will
+  /// automatically await it if needed. This constructor only accepts lvalues or
+  /// non-movable rvalues. Movable rvalues would be unsafe here, and are deliberately
+  /// rejected.
+  template <typename A>
+    requires(tmc::detail::is_awaitable<std::remove_reference_t<A>> &&
+             requires(A& Obj) { Obj.cancel(); } &&
+             std::is_reference_v<tmc::detail::forward_awaitable<A>>)
+  explicit cancellable(A&& Obj) : awaitable(static_cast<A&&>(Obj)), canceller{} {}
+};
+
+// Deduction guides pick the storage types that the matching constructor fills:
+// the awaitable is forwarded (owned-by-value for a movable rvalue, by-reference
+// otherwise); the canceller is stored as-is (form 1), wrapped in a
+// `cancel_caller` (form 2), or replaced by the empty `cancel_self_t` (form 3).
+// Their constraints mirror the constructors' so the right type is deduced.
+template <typename A, typename C>
+  requires(
+    tmc::traits::executable_kind_v<std::decay_t<C>> ==
+    tmc::traits::executable_kind::CALLABLE
+  )
+cancellable(A&&, C&&) -> cancellable<tmc::detail::forward_awaitable<A>, std::decay_t<C>>;
+
+template <typename A, typename C>
+  requires(
+    tmc::traits::executable_kind_v<std::decay_t<C>> ==
+      tmc::traits::executable_kind::UNKNOWN &&
+    requires(C& Obj) { Obj.cancel(); }
+  )
+cancellable(A&&, C&&) -> cancellable<
+  tmc::detail::forward_awaitable<A>,
+  tmc::detail::cancel_caller<tmc::detail::forward_awaitable<C>>>;
+
+template <typename A>
+  requires(
+    tmc::detail::is_awaitable<std::remove_reference_t<A>> &&
+    requires(A& Obj) { Obj.cancel(); } &&
+    std::is_reference_v<tmc::detail::forward_awaitable<A>>
+  )
+cancellable(A&&)
+  -> cancellable<tmc::detail::forward_awaitable<A>, tmc::detail::cancel_self_t>;
+
+namespace detail {
+// Compile-time check whether the canceller of a `tmc::cancellable` is
+// async (returns an awaitable rather than performing the cancellation directly).
+template <typename Awaitable, typename Canceller> consteval bool canceller_is_async() {
+  using Pair = tmc::cancellable<Awaitable, Canceller>;
+  if constexpr (std::is_same_v<Canceller, cancel_self_t>) {
+    // self-cancel (form 3)
+    return tmc::traits::is_awaitable<decltype(std::declval<Pair&>().awaitable.cancel())>;
+  } else {
+    // a callable canceller (form 1) or object with `cancel()` method (form 2)
+    return tmc::traits::is_awaitable<decltype(std::declval<Pair&>().canceller())>;
+  }
+}
+} // namespace detail
+
+/// Awaits all of the provided awaitables and returns the result of the first
+/// one to complete in a `std::variant`. The `index()` of the returned variant
+/// indicates which awaitable completed first; its value holds that awaitable's
+/// result. A void-returning awaitable's slot holds a `std::monostate`.
+///
+/// Each awaitable must be paired with a canceller using `tmc::cancellable()`.
+/// As soon as the first awaitable completes (the winner), the cancellers of all of the
+/// others (losers) are run; cancellers that return awaitables (async cancel) are awaited.
+/// Results from losers are discarded.
+///
+/// If multiple awaitables complete simultaneously, the winner is the awaitable with the
+/// lower index (leftmost parameter). All losers are cancelled, even those that may have
+/// already completed. Therefore, it must be safe to cancel a completed awaitable.
+///
+/// Implementation note: `select()` waits for cancelled losers to complete before
+/// returning. This is required since wrapped operations borrow storage from this
+/// coroutine frame, so they must all complete before it is destroyed. Consequently, a
+/// canceller that cannot truly stop its operation will delay the return of `select()`
+/// until that operation completes on its own.
+template <typename... Awaitable, typename... Canceller>
+tmc::task<std::variant<tmc::detail::void_to_monostate<
+  typename tmc::detail::get_awaitable_traits<Awaitable>::result_type>...>>
+select(tmc::cancellable<Awaitable, Canceller>... Pairs) {
+  static_assert(sizeof...(Awaitable) > 0, "select() requires at least one awaitable.");
+  static_assert(
+    sizeof...(Awaitable) < TMC_PLATFORM_BITS,
+    "select() supports at most 63 awaitables (31 on 32-bit platforms)."
+  );
+  using variant_type = std::variant<tmc::detail::void_to_monostate<
+    typename tmc::detail::get_awaitable_traits<Awaitable>::result_type>...>;
+  constexpr size_t Count = sizeof...(Awaitable);
+
+  // Forward each awaitable with its original value category so the awaitable's own
+  // lvalue/rvalue qualification is respected.
+  auto each =
+    tmc::spawn_tuple(static_cast<Awaitable&&>(Pairs.awaitable)...).result_each();
+
+  // Wait for at least one operation to complete.
+  size_t winner = co_await each;
+
+  // Move the winner's result into the variant slot for its index.
+  std::optional<variant_type> result;
+  auto storeWinner = [&]<size_t I>(std::integral_constant<size_t, I>) {
+    using VarElem = std::variant_alternative_t<I, variant_type>;
+    using Stored = std::remove_reference_t<decltype(each.template get<I>())>;
+    if constexpr (std::is_same_v<Stored, VarElem>) {
+      result.emplace(std::in_place_index<I>, std::move(each.template get<I>()));
+    } else {
+      // Non-default-constructible results are stored wrapped in std::optional.
+      result.emplace(std::in_place_index<I>, std::move(*each.template get<I>()));
+    }
+  };
+  [&]<size_t... I>(std::index_sequence<I...>) {
+    ((winner == I ? (storeWinner(std::integral_constant<size_t, I>{}), void()) : void()),
+     ...);
+  }(std::make_index_sequence<Count>{});
+
+  // Cancel every awaitable except the winner. The cancellation action of a loser is, per
+  // the cancellable forms:
+  // - self-cancel (form 3): `Pair.awaitable.cancel()`;
+  // - a callable canceller (form 1) or `cancel_caller` (form 2):
+  //   `Pair.canceller()`.
+  //
+  // This is split on whether ANY canceller is async; a fold expression cannot contain a
+  // per-element `if constexpr` check, so it must go outside.
+  if constexpr (!(tmc::detail::canceller_is_async<Awaitable, Canceller>() || ...)) {
+    // All cancellations are sync. The fold expression is a plain call.
+    size_t idx = 0;
+    auto cancelSync = [](auto& Pair) {
+      if constexpr (std::is_same_v<
+                      std::remove_reference_t<decltype(Pair.canceller)>,
+                      tmc::detail::cancel_self_t>) {
+        Pair.awaitable.cancel();
+      } else {
+        Pair.canceller();
+      }
+    };
+    (((idx++ == winner) ? void() : cancelSync(Pairs)), ...);
+  } else {
+    // At least once cancellation is async. The fold expression's `co_await` must resolve
+    // for all cancellations, so sync cancellations are projected with a dummy awaitable.
+    size_t idx = 0;
+    auto cancelAsync = [](auto& Pair) -> decltype(auto) {
+      using Canceller_t = std::remove_reference_t<decltype(Pair.canceller)>;
+      if constexpr (std::is_same_v<Canceller_t, tmc::detail::cancel_self_t>) {
+        if constexpr (tmc::traits::is_awaitable<decltype(Pair.awaitable.cancel())>) {
+          return Pair.awaitable.cancel();
+        } else {
+          Pair.awaitable.cancel();
+          return tmc::detail::cancel_noop{};
+        }
+      } else {
+        if constexpr (tmc::traits::is_awaitable<decltype(Pair.canceller())>) {
+          return Pair.canceller();
+        } else {
+          Pair.canceller();
+          return tmc::detail::cancel_noop{};
+        }
+      }
+    };
+    (((idx++ == winner) ? void() : (void)(co_await cancelAsync(Pairs))), ...);
+  }
+
+  // Drain the remaining (now-cancelled) awaitables. Their results are
+  // discarded, but they must all complete before `each` is destroyed.
+  for (size_t i = co_await each; i != each.end(); i = co_await each) {
+    // discard
+  }
+
+  co_return std::move(*result);
+}
+} // namespace tmc