Merge pull request #1297 from aurianer/require_started_documentation

Add documentation for `require_started`

docs/api.rst

@@ -99,6 +99,12 @@ All sender adaptors are `customization point objects (CPOs)
    :language: c++
    :start-at: #include
 
+.. doxygenvariable:: pika::execution::experimental::require_started
+
+.. literalinclude:: ../examples/documentation/require_started_documentation.cpp
+   :language: c++
+   :start-at: #include
+
 .. doxygenvariable:: pika::execution::experimental::split_tuple
 
 .. literalinclude:: ../examples/documentation/split_tuple_documentation.cpp

examples/documentation/CMakeLists.txt

@@ -9,6 +9,7 @@ set(example_programs
     drop_value_documentation
     hello_world_documentation
     init_hpp_documentation
+    require_started_documentation
     split_tuple_documentation
     unpack_documentation
     when_all_vector_documentation
@@ -32,3 +33,10 @@ foreach(example_program ${example_programs})
     pika_add_example_test("documentation" ${example_program} ${${example_program}_PARAMETERS})
   endif()
 endforeach()
+
+if(PIKA_WITH_TESTS AND PIKA_WITH_TESTS_EXAMPLES)
+  set_tests_properties(
+    tests.examples.documentation.require_started_documentation PROPERTIES PASS_REGULAR_EXPRESSION
+                                                                          "terminate called"
+  )
+endif()

examples/documentation/require_started_documentation.cpp

@@ -0,0 +1,48 @@
+//  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 <cassert>
+#include <cstdlib>
+#include <exception>
+#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{};
+
+    {
+        // require_started forwards values received from the predecessor sender
+        auto s = ex::just(42) | ex::require_started() |
+            ex::then([]([[maybe_unused]] auto&& i) { assert(i == 42); });
+        tt::sync_wait(std::move(s));
+    }
+
+    {
+        // The termination is ignored with discard, the sender is from the user's perspective
+        // rightfully not used
+        auto s = ex::just() | ex::require_started();
+        s.discard();
+    }
+
+    {
+        // The require_started sender terminates on destruction if it has not been used
+        auto s = ex::just() | ex::require_started();
+    }
+    assert(false);
+
+    pika::finalize();
+    pika::stop();
+    return 0;
+}

libs/pika/execution/include/pika/execution/algorithms/require_started.hpp

@@ -439,7 +439,7 @@ namespace pika {
 #endif
 
     namespace execution::experimental {
-        inline constexpr struct require_started_t final
+        struct require_started_t final
         {
             template <typename Sender, PIKA_CONCEPT_REQUIRES_(is_sender_v<Sender>)>
             constexpr PIKA_FORCEINLINE auto
@@ -453,7 +453,22 @@ namespace pika {
             {
                 return detail::partial_algorithm<require_started_t>{};
             }
-        } require_started{};
+        };
+
+        /// \brief Diagnose if a sender has not been started and terminates on destruction. It
+        /// forwards the values of the predecessor sender.
+        ///
+        /// Sender adaptor that takes any sender and returns a new sender that sends the same values
+        /// as the predecessor sender.
+        ///
+        /// The destructor terminates if the sender has not been connected or if the
+        /// operation state has not been started.
+        /// The operation state of a \p require_started sender is allowed to not be started if it
+        /// has been explicitly requested with the \p discard member function.
+        ///
+        /// Added in 0.21.0.
+        inline constexpr require_started_t require_started{};
+
     }    // namespace execution::experimental
 
 #undef PIKA_DETAIL_REQUIRE_STARTED_MODE_PARAMETER