std::experi...al::when_any(3)

okay so bestie, we're in the C++ Standard Libary manual and today's main character is std::experimental::when_any. yes, that's the actual manual name up top — we don't make the rules 💅

🌸 NAME 🌸

std::experimental::when_any — std::experimental::when_any

periodt. that's the name, no notes 💖

🦋 Synopsis 🦋

          Defined in header <experimental/future>
          template< class Sequence >

          struct when_any_result {
       (concurrency
              std::size_t index;
       TS)
              Sequence futures;

          };
          template< class InputIt >

          auto when_any( InputIt first, InputIt last )
       (1) (concurrency
                                                                                  TS)
              -> future<when_any_result<std::vector<typename
          std::iterator_traits<InputIt>::value_type>>>;
          template< class... Futures >

          auto when_any( Futures&&... futures )
       (2) (concurrency
                                                                                  TS)
              ->
          future<when_any_result<std::tuple<std::decay_t<Futures>...>>>;

so what this does is create a future object that becomes ready when at least one of the input futures and shared_futures becomes ready. 🫶

🚨 Undefined behavior alert: the behavior is undefined if any input future or shared_future is invalid. do not play with invalid futures, bestie 😭

in particular, let Sequence be std::vector<typename std::iterator_traits<InputIt>::value_type> for (1) and std::tuple<std::decay_t<Futures>...> for (2). this function template creates a shared state containing when_any_result<Sequence> and returns a future referring to the shared state. ✨

every input future is moved into the corresponding object in the futures member of the when_any_result<Sequence> in the shared state, and every input shared_future is copied to the corresponding object in the futures member of the when_any_result<Sequence> in the shared state. the order of the objects in the Sequence matches the order of arguments. no cap 🔥

now the overload-resolution gatekeeping, because of course there's gatekeeping:

1. this function does not participate in overload resolution unless InputIt's value type (i.e., typename std::iterator_traits<InputIt>::value_type) is a std::experimental::future or std::experimental::shared_future. 💅
2. this function does not participate in overload resolution unless every argument is either a (possibly cv-qualified) std::experimental::shared_future or a cv-unqualified std::experimental::future. (Formally, for every type Fn in Futures, either std::remove_reference_t<Fn> is std::experimental::future<Rn>, or std::decay_t<Fn> is std::experimental::shared_future<Rn>.) 🎀

after this call, every input future is no longer valid; every input shared_future remains valid. iconic behavior honestly 👑

💖 Return value 💖

a future referring to the shared state created by the call. the future is always valid(), and it becomes ready when at least one of the input futures and shared_futures the call has is ready. the index member of the when_any_result contains the position of the ready future or shared_future in the futures member. 🌟

1. if the range is empty (i.e., first == last), the returned future is ready immediately; the futures field of the when_any_result is an empty vector, and the index field is size_t(-1). 🍓
2. if no argument is provided, the returned future is ready immediately; the futures field of the when_any_result is an empty tuple, and the index field is size_t(-1). 🧚

okay that's the whole page, bestie 🫶 this lil transmission came from source/version http://cppreference.com, dated 2024.06.10 — mwah 💋✨