Allow FnOnce to be split into any number of FnOnce

The splitting mechanism just holds a reference to the original FnOnce
so two calls to different splits of the FnOnce will panic.

The splittinf mechanism also tracks the calls in debug mode to provide
a more clear crash indicating two calls were made, instead of just that
the FnOnce was moved from (which is what happens when it's run).

Author: danakj

subspace/fn/fn_defn.h

@@ -64,6 +64,12 @@ struct Invoker {
     return f(::sus::forward<Args>(args)...);
   }
 
+  template <class R, class... Args>
+  static R object_call_once(const union Storage& s, Args... args) {
+    F& f = *static_cast<F*>(s.object);
+    return ::sus::move(f)(::sus::forward<Args>(args)...);
+  }
+
   template <class R, class... Args>
   static R fnptr_call_const(const union Storage& s, Args... args) {
     const F f = reinterpret_cast<const F>(s.fnptr);
@@ -95,6 +101,12 @@ concept ConvertsToFunctionPointer = requires(F f) {
   { +f } -> IsFunctionPointer;
 };
 
+template <class F, class R, class... Args>
+concept CallableOnceMut =
+    !FunctionPointer<F, R, Args...> && requires(F && f, Args... args) {
+      { ::sus::move(f)(args...) } -> std::convertible_to<R>;
+    };
+
 template <class F, class R, class... Args>
 concept CallableMut =
     !FunctionPointer<F, R, Args...> && requires(F & f, Args... args) {
@@ -434,23 +446,23 @@ class [[sus_trivial_abi]] FnOnce<R(CallArgs...)> {
   /// Construction from a non-capturing lambda.
   ///
   /// #[doc.overloads=ctor.lambda]
-  template <__private::CallableMut<R, CallArgs...> F>
+  template <__private::CallableOnceMut<R, CallArgs...> F>
     requires(__private::ConvertsToFunctionPointer<F>)
   constexpr FnOnce(F&& object sus_lifetimebound) noexcept {
     storage_.object = ::sus::mem::addressof(object);
     invoke_ = &__private::Invoker<
-        std::remove_reference_t<F>>::template object_call_mut<R, CallArgs...>;
+        std::remove_reference_t<F>>::template object_call_once<R, CallArgs...>;
   }
 
   /// Construction from a capturing lambda or other callable object.
   ///
   /// #[doc.overloads=ctor.capturelambda]
-  template <__private::CallableMut<R, CallArgs...> F>
+  template <__private::CallableOnceMut<R, CallArgs...> F>
     requires(!__private::ConvertsToFunctionPointer<F>)
   constexpr FnOnce(F&& object sus_lifetimebound) noexcept {
     storage_.object = ::sus::mem::addressof(object);
     invoke_ = &__private::Invoker<
-        std::remove_reference_t<F>>::template object_call_mut<R, CallArgs...>;
+        std::remove_reference_t<F>>::template object_call_once<R, CallArgs...>;
   }
 
   /// Construction from FnMut.
@@ -489,10 +501,51 @@ class [[sus_trivial_abi]] FnOnce<R(CallArgs...)> {
     return *this;
   }
 
+  /// A split FnOnce object, which can be used to construct other FnOnce
+  /// objects, but enforces that only one of them is called.
+  ///
+  /// The Split object must not outlive the FnOnce it's constructed from or
+  /// Undefined Behaviour results.
+  class Split {
+   public:
+    Split(FnOnce& fn sus_lifetimebound) : fn_(fn) {}
+
+    // Not Copy or Move, only used to construct FnOnce objects, which are
+    // constructible from this type.
+    Split(Split&&) = delete;
+    Split& operator=(Split&&) = delete;
+
+    /// Runs the underlying `FnOnce`. The `FnOnce` may only be called a single
+    /// time and will panic on the second call.
+    R operator()(CallArgs... args) && {
+      return ::sus::move(fn_)(::sus::forward<CallArgs>(args)...);
+    }
+
+   private:
+    FnOnce& fn_;
+  };
+
   // Not copyable.
   FnOnce(const FnOnce&) noexcept = delete;
   FnOnce& operator=(const FnOnce&) noexcept = delete;
 
+  /// A `FnOnce` can be split into any number of `FnOnce` objects, while
+  /// enforcing that the underlying function is only called a single time.
+  ///
+  /// This method returns a type that can convert into any number of `FnOnce`
+  /// objects. If two of them are called, the second call will panic.
+  ///
+  /// The returned object must not outlive the `FnOnce` object it is constructed
+  /// from, this is normally enforced by only using the `FnOnce` type in
+  /// function parameters, which ensures it lives for the entire function body,
+  /// and calling `split()` to construct temporary objects for passing to other
+  /// functions that receive a `FnOnce`. The result of `split()` should never be
+  /// stored as a member of an object.
+  ///
+  /// Only callable on an lvalue FnOnce (typically written as a function
+  /// parameter) as an rvalue can be simply passed along without splitting.
+  constexpr Split split() & noexcept sus_lifetimebound { return Split(*this); }
+
   /// Runs and consumes the closure.
   inline R operator()(CallArgs... args) && {
     ::sus::check(invoke_);  // Catch use-after-move.
@@ -509,7 +562,7 @@ class [[sus_trivial_abi]] FnOnce<R(CallArgs...)> {
       __private::FunctionPointer<R, CallArgs...> auto ptr) noexcept {
     return FnOnce(ptr);
   }
-  template <__private::CallableMut<R, CallArgs...> F>
+  template <__private::CallableOnceMut<R, CallArgs...> F>
   constexpr static auto from(F&& object sus_lifetimebound) noexcept {
     return FnOnce(::sus::forward<F>(object));
   }

subspace/fn/fn_unittest.cc

@@ -625,9 +625,107 @@ TEST(Fn, CallsCorrectOverload) {
   EXPECT_EQ(mut_calls, 2);
 }
 
-TEST(Fn, Lvalue) {
-  Fn<void()> f([]() {});
-  Fn<void()> g([i = 1]() { (void)i; });
+TEST(Fn, Clone) {
+  static_assert(sus::mem::Clone<Fn<i32()>>);
+  auto clones_fn = [](Fn<i32()> f) {
+    return [](FnOnce<i32()> f1) { return sus::move(f1)(); }(f.clone()) +
+           [](FnOnce<i32()> f2) { return sus::move(f2)(); }(f.clone());
+  };
+  EXPECT_EQ(4, clones_fn([]() { return 2_i32; }));
+
+  static_assert(sus::mem::Clone<FnMut<i32()>>);
+  auto clones_fnmut = [](FnMut<i32()> f) {
+    return [](FnOnce<i32()> f1) { return sus::move(f1)(); }(f.clone()) +
+           [](FnOnce<i32()> f2) { return sus::move(f2)(); }(f.clone());
+  };
+  EXPECT_EQ(5, clones_fnmut([i = 1_i32]() mutable {
+              i += 1;
+              return i;
+            }));
+
+  static_assert(!sus::mem::Clone<FnOnce<i32()>>);
+}
+
+TEST(FnOnce, Split) {
+  // The return type of split() is not Copy or Move
+  static_assert(
+      !::sus::mem::Copy<decltype(std::declval<FnOnce<void()>&>().split())>);
+  static_assert(
+      !::sus::mem::Move<decltype(std::declval<FnOnce<void()>&>().split())>);
+  // It's only used to build more FnOnce objects.
+  static_assert(
+      ::sus::construct::Into<decltype(std::declval<FnOnce<void()>&>().split()),
+                             FnOnce<void()>>);
+  // And not FnMut or Fn, as that loses the intention to only call it once. This
+  // is implemented by making the operator() callable as an rvalue only.
+  static_assert(
+      !::sus::construct::Into<decltype(std::declval<FnOnce<void()>&>().split()),
+                              FnMut<void()>>);
+  static_assert(
+      !::sus::construct::Into<decltype(std::declval<FnOnce<void()>&>().split()),
+                              Fn<void()>>);
+
+  // split() as rvalues. First split is run.
+  auto rsplits_fnonce = [](FnOnce<i32()> f) {
+    i32 a = [](FnOnce<i32()> f) { return sus::move(f)(); }(f.split());
+    i32 b = [](FnOnce<i32()>) {
+      // Don't run the `FnOnce` as only one of the splits may run the
+      // FnOnce.
+      return 0_i32;
+    }(f.split());
+    return a + b;
+  };
+  EXPECT_EQ(2, rsplits_fnonce([i = 1_i32]() mutable {
+              i += 1;
+              return i;
+            }));
+
+  // split() as rvalues. Second split is run.
+  auto rsplits_fnonce2 = [](FnOnce<i32()> f) {
+    i32 a = [](FnOnce<i32()>) {
+      // Don't run the `FnOnce` as only one of the splits may run the
+      // FnOnce.
+      return 0_i32;
+    }(f.split());
+    i32 b = [](FnOnce<i32()> f) { return sus::move(f)(); }(f.split());
+    return a + b;
+  };
+  EXPECT_EQ(2, rsplits_fnonce([i = 1_i32]() mutable {
+              i += 1;
+              return i;
+            }));
+
+  // split() as lvalues. First split is run.
+  auto lsplits_fnonce = [](FnOnce<i32()> f) {
+    auto split = f.split();
+    i32 a = [](FnOnce<i32()> f) { return sus::move(f)(); }(f);
+    i32 b = [](FnOnce<i32()>) {
+      // Don't run the `FnOnce` as only one of the splits may run the
+      // FnOnce.
+      return 0_i32;
+    }(f);
+    return a + b;
+  };
+  EXPECT_EQ(2, lsplits_fnonce([i = 1_i32]() mutable {
+              i += 1;
+              return i;
+            }));
+
+  // split() as lvalues. Second split is run.
+  auto lsplits_fnonce2 = [](FnOnce<i32()> f) {
+    auto split = f.split();
+    i32 a = [](FnOnce<i32()>) {
+      // Don't run the `FnOnce` as only one of the splits may run the
+      // FnOnce.
+      return 0_i32;
+    }(f);
+    i32 b = [](FnOnce<i32()> f) { return sus::move(f)(); }(f);
+    return a + b;
+  };
+  EXPECT_EQ(2, lsplits_fnonce([i = 1_i32]() mutable {
+              i += 1;
+              return i;
+            }));
 }
 
 }  // namespace