Make unifex::async_scope::spawn return a unifex::future<> (#372)

* Make async_scope::spawn return a lazy<>

This diff changes `unifex::async_scope::spawn(Sender auto)` to return a
new type, `unifex::lazy<...>`.  `lazy<>` is a _Sender_ that completes
with the result of the _Sender_ given to `spawn`.

* Fix memory leak

* Rationalize the names of some internal bits

* Fuse the promise and the operation state

This diff merges the spawned operation's promise with its operation
state so there's only one allocation.

One consequence of this change is that outstanding operations don't
record themselves as complete within their corresponding scope until the
associated `lazy<>` is either connected and started, or discarded.

* Fix build

Looks like our CI turns on exhaustive switch warnings, which I broke.

* Fix infinite hang in create_test.cpp

* Cleanup

* Last bit of cleanup before bed

* Try to fix ASAN failure

In the light of the morning, I think it's wrong to set the event before
requesting stop on the stop source because setting the event could lead
to destruction of the operation state, invalidating the stop source.

* Fix request_stop()

The callers of `request_stop()` are not owners so they may not call
`decref()`, which means I can't invoke `set_done()` from
`request_stop()`.

* Clean up, bug fixes, comments

Among other clean-up, this diff fixes a stack-use-after-return in
`future<>`'s `connect()`.

* Add constraints and run clang-format

* Comments, tests, bug fixes, and clang-format

* Restore nothrow assertion in detached_spawn_call_on

* Round out the async_scope tests

add async_scope::attach (#392)

* returned `Sender` needs to be connected and started
* avoids paying penalty of `future<>`

Fix `record_done` ordering in `async_scope::attach` (#424)

* `record_done`, which decrements outstanding operation count, must be called after `set_*`
* add regression test

fix cancellation race in async_scope::attach* (#425)

* use refcount to pass ownership of `deliver_result`
* replace `fused_stop_source` with `inplace_stop_source`

make `async_scope::attached_sender` copyable (#428)

* copy constructor calls `async_scope::try_record_start` internally
* copy of attached Sender will increment outstanding number of
  operations on async_scope

`async_scope::attach` cleanup (#433)

* remove unused template argument
* add missing test case

update `async_scope` docs (#434)

* spawn() -> detached_spawn()
* spawn() returns a `future`
* add missing public methods

add `async_scope::attach` docs (#434)

fix `async_scope_test::attach_record_done` (#437)

fix `tag_invoke(CPO)` in `async_scope` (#462)

add `unifex::v2::async_scope` (#463)

* simpler than `unifex::v1::async_scope` (`nest()` and `join()`)
* does not support cancellation

Introduce unifex::nest() (#468)

`unifex::nest()` is a CPO that delegates to either a `tag_invoke`
customization taking a *Sender* and a "scope" reference, or to a
member function on the given scope that takes a *Sender*.  This
diff wires `unifex::nest()` to the `nest()` member function on
`v2::async_scope` and to the `attach()` member function on
`v1::async_scope`.

Introduce spawn_detached(sender, scope, allocator) (#470)

This diff introduces a new algorithm, `unifex::spawn_detached()`.
`spawn_detached` takes a sender, an "async scope", and an optional
allocator.  It nests the sender in the scope with `unifex::nest`,
allocates and operation state using the allocator, and starts that
operation.  The given async scope may be anything that `nest()`
supports, which currently includes both `v1::async_scope` and
`v2::async_scope`.

Add an internal receiver to v2::async_scope's nest op (#484)

While writing `unifex::spawn_future()`, I discovered that waiting until
the destructor of the `v2::async_scope`'s `nest()` operation to drop the
scope reference is too late (it led to hangs).  This diff adds an
internal receiver to the nest operation so we can detect when the
operation is complete (which is likely before the operation state is
destroyed) and drop the reference as soon as we reach that state.

Fix stop_when's handling of stop requests (#500)

* Fix stop_when's handling of stop requests

When trying to sync PR #495 into our internal repo, I discovered that
there's a lifetime issue in `stop_when()`.  If the `stop_when()`
operation receives a stop request from its Receiver and the
last-to-finish child operation completes synchronously in response to
the stop request then `stop_when()`'s stop callback will access the
internal stop source after it's been destroyed.

This first diff just formats `test/stop_when_test.cpp` and
`include/unifex/stop_when.hpp` with `clang-format` in preparation for
fixing the above problem.

* Add a broken unit test

This diff adds a unit test to `test/stop_when_test.cpp` that crashes
when ASAN is enabled because it dereferences a destroyed
`inplace_stop_source`.

* Increment stop_when's refcount in its stop callback

This diff fixes the broken test from the previous diff by incrementing
the `stop_when` operation's refcount while processing a stop request
from the receiver.

Add spawn_future() (#489)

This diff adds `unifex::spawn_future(Sender, Scope)`.

Implement async_scope::spawn with spawn_future (#501)

This diff reimplements the `v1::async_scope::spawn()` method in terms of
the newly-added `unifex::spawn_future()` algorithm.  I had to delete a
few tests that exercise behaviour that's no longer supported.

Work around an MSVC bug in C++20 mode (#492)

* merge unit test that depends on `v2/async_scope`

Co-authored-by: Ian Petersen <ispeters@gmail.com>

Author: ispeters

doc/api_reference.md

@@ -38,6 +38,7 @@
   * `with_query_value()`
   * `with_allocator()`
   * `done_as_optional()`
+  * `nest()`
 * Sender Types
   * `async_trace_sender`
 * Sender Queries
@@ -711,6 +712,13 @@ task<void> g() {
 }
 ```
 
+### `nest(Sender sender, Scope& scope) -> Sender`
+
+`nest` registers the given *Sender* with the given "scope", which should be of a
+type that works like `v1::async_scope` or `v2::async_scope`. A *Sender* that has
+been registered with a scope will prevent that scope from being joined until the
+*Sender* has either been discarded or executed.
+
 ## Sender Types
 
 ### `async_trace_sender`
@@ -1201,8 +1209,10 @@ namespace unifex
     // Asserts if the sender returned from cleanup has not yet completed.
     ~async_scope();
 
-    // Returns a sender that, when started, marks this scope as cleaned up,
-    // requests stop on the internal stop source, and then waits for all
+    // Returns a sender that, when started, marks this scope so that no more
+    // work can be spawned within it,
+    // requests stop on the internal stop source,
+    // i.e. cancellation of all outstanding work, and then waits for all
     // outstanding work to complete.
     //
     // The sender returned from cleanup must complete before this scope is
@@ -1212,28 +1222,87 @@ namespace unifex
     // times in series or in parallel).
     [[nodiscard]] sender auto cleanup() noexcept;
 
-    // Connects sender to an internal receiver and starts the operation.  Once
+    // Returns a sender that, when started, marks this scope so that no more
+    // work can be spawned within it and then waits for all outstanding work
+    // to complete.
+    //
+    // The sender returned from complete must complete before this scope is
+    // destroyed.
+    //
+    // complete is thread-safe and idempotent (i.e. it can be invoked multiple
+    // times in series or in parallel).
+    [[nodiscard]] sender auto complete() noexcept;
+
+    // Returns a stop token from the scope's internal stop source.
+    inplace_stop_token get_stop_token() noexcept;
+
+    // Marks the scope so that no more work can be spawned within it,
+    // requests stop on the internal stop source,
+    // i.e. cancellation of all outstanding work
+    void request_stop() noexcept;
+
+    // Implemented as (void)spawn(sender).
+    void detached_spawn(sender);
+
+    // Implemented as detached_spawn(on(scheduler, sender)).
+    void detached_spawn_on(scheduler, sender);
+
+    // Implemented as detached_spawn_on(scheduler, just_from(invocable)).
+    void detached_spawn_call_on(scheduler, invocable);
+
+    // Connects sender to an internal receiver and starts the operation. Once
     // started, the given sender must complete with void or done; completing
     // with an error will result in a call to std::terminate.
     //
     // The receiver to which the sender is connected responds to get_stop_token
     // with a stoppable token that becomes stopped when clean-up begins.
     //
     // Space for the operation state is allocated with std::make_unique and
-    // so this operation may throw if the allocation fails.  This operation may
+    // so this operation may throw if the allocation fails. This operation may
     // also throw if connect throws.
     //
     // Once connect has succeeded, start will only be called if this scope has
     // not yet been cleaned up; if a call to spawn loses a race with a call to
     // cleanup, the operation state created by connect will be destroyed and
     // deallocated without being started.
-    void spawn(sender);
+    //
+    // future is a handle to an eagerly-started operation; it is also a Sender,
+    // the result is retreived by connecting it to an appropriate Receiver
+    // and starting the resulting Operation.
+    //
+    // Discarding a future without connecting or starting it requests cancellation
+    // of the associated operation and discards the operation's result when it
+    // ultimately completes.
+    //
+    // Requesting cancellation of a connected-and-started future will also request
+    // cancellation of the associated operation.
+    future spawn(sender);
 
-    // Implemented as spawn(on(scheduler, sender)).
-    void spawn_on(scheduler, sender);
+    // Implemented as detached_spawn(on(scheduler, sender)).
+    future spawn_on(scheduler, sender);
 
     // Implemented as spawn_on(scheduler, just_from(invocable)).
-    void spawn_call_on(scheduler, invocable);
+    future spawn_call_on(scheduler, invocable);
+
+    // Returns a new sender that, when connected and started, connects and starts
+    // the given sender.
+    //
+    // Returned sender owns a reference to this async_scope. Discarding the sender
+    // prior to connecting it or discarding the operation prior to starting it
+    // discards the reference to this async_scope.
+    //
+    // The receiver to which the sender is connected responds to get_stop_token
+    // with a stoppable token that becomes stopped when clean-up begins.
+    [[nodiscard]] sender auto attach(sender);
+
+    // Implemented as attach(just_from(fun))
+    [[nodiscard]] sender auto attach_call(fun);
+
+    // Implemented as attach(on(scheduler, sender))
+    [[nodiscard]] sender auto attach_on(scheduler, sender);
+
+    // Implemented as attach_on(scheduler, just_from(fun))
+    [[nodiscard]] sender auto attach_call_on(scheduler, fun);
   };
 }
 ```

include/unifex/config.hpp.in

@@ -176,6 +176,7 @@
   #define UNIFEX_DIAGNOSTIC_IGNORE_INIT_LIST_LIFETIME
   #define UNIFEX_DIAGNOSTIC_IGNORE_FLOAT_EQUAL
   #define UNIFEX_DIAGNOSTIC_IGNORE_CPP2A_COMPAT
+  #define UNIFEX_DIAGNOSTIC_IGNORE_UNUSED_RESULT
 #else // ^^^ defined(_MSC_VER) ^^^ / vvv !defined(_MSC_VER) vvv
   #if defined(__GNUC__) || defined(__clang__)
     #define UNIFEX_PRAGMA(X) _Pragma(#X)
@@ -194,12 +195,15 @@
       UNIFEX_DIAGNOSTIC_IGNORE("-Wfloat-equal")
     #define UNIFEX_DIAGNOSTIC_IGNORE_CPP2A_COMPAT \
       UNIFEX_DIAGNOSTIC_IGNORE("-Wc++2a-compat")
+    #define UNIFEX_DIAGNOSTIC_IGNORE_UNUSED_RESULT \
+      UNIFEX_DIAGNOSTIC_IGNORE("-Wunused-result")
   #else
     #define UNIFEX_DIAGNOSTIC_PUSH
     #define UNIFEX_DIAGNOSTIC_POP
     #define UNIFEX_DIAGNOSTIC_IGNORE_INIT_LIST_LIFETIME
     #define UNIFEX_DIAGNOSTIC_IGNORE_FLOAT_EQUAL
     #define UNIFEX_DIAGNOSTIC_IGNORE_CPP2A_COMPAT
+    #define UNIFEX_DIAGNOSTIC_IGNORE_UNUSED_RESULT
   #endif
 #endif // MSVC/Generic configuration switch
 

include/unifex/fused_stop_source.hpp

@@ -18,6 +18,7 @@
 #include <optional>
 
 #include <unifex/inplace_stop_token.hpp>
+
 #include <unifex/detail/prologue.hpp>
 
 namespace unifex {

include/unifex/nest.hpp

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * Licensed under the Apache License Version 2.0 with LLVM Exceptions
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *   https://llvm.org/LICENSE.txt
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#pragma once
+
+#include <unifex/config.hpp>
+#include <unifex/bind_back.hpp>
+#include <unifex/sender_concepts.hpp>
+#include <unifex/tag_invoke.hpp>
+
+#include <unifex/detail/prologue.hpp>
+
+namespace unifex {
+
+namespace _nest_cpo {
+
+inline const struct _nest_fn final {
+private:
+  template <typename Scope, typename Sender>
+  using nest_member_result_t =
+      decltype(UNIFEX_DECLVAL(Scope&).nest(UNIFEX_DECLVAL(Sender)));
+
+  template <typename Scope, typename Sender>
+  static constexpr bool is_nest_member_nothrow_v =
+      noexcept(UNIFEX_DECLVAL(Scope&).nest(UNIFEX_DECLVAL(Sender)));
+
+  struct deref;
+
+public:
+  template(typename Sender, typename Scope)  //
+      (requires typed_sender<Sender> AND tag_invocable<_nest_fn, Sender, Scope&>
+           AND typed_sender<tag_invoke_result_t<_nest_fn, Sender, Scope&>>)  //
+      auto
+      operator()(Sender&& sender, Scope& scope) const
+      noexcept(is_nothrow_tag_invocable_v<_nest_fn, Sender, Scope&>)
+          -> tag_invoke_result_t<_nest_fn, Sender, Scope&> {
+    return tag_invoke(_nest_fn{}, static_cast<Sender&&>(sender), scope);
+  }
+
+  template(typename Sender, typename Scope)  //
+      (requires typed_sender<Sender> AND(
+          !tag_invocable<_nest_fn, Sender, Scope&>)
+           AND typed_sender<nest_member_result_t<Scope, Sender>>)  //
+      auto
+      operator()(Sender&& sender, Scope& scope) const
+      noexcept(is_nest_member_nothrow_v<Scope, Sender>)
+          -> nest_member_result_t<Scope, Sender> {
+    return scope.nest(static_cast<Sender&&>(sender));
+  }
+
+  template <typename Scope>
+  constexpr auto operator()(Scope& scope) const
+      noexcept(is_nothrow_callable_v<tag_t<bind_back>, deref, Scope*>)
+          -> bind_back_result_t<deref, Scope*>;
+} nest{};
+
+struct _nest_fn::deref final {
+  template <typename Sender, typename Scope>
+  constexpr auto operator()(Sender&& sender, Scope* scope) const
+      noexcept(noexcept(_nest_fn{}(static_cast<Sender&&>(sender), *scope)))
+          -> decltype(_nest_fn{}(static_cast<Sender&&>(sender), *scope)) {
+    return _nest_fn{}(static_cast<Sender&&>(sender), *scope);
+  }
+};
+
+template <typename Scope>
+inline constexpr auto _nest_fn::operator()(Scope& scope) const
+    noexcept(is_nothrow_callable_v<tag_t<bind_back>, deref, Scope*>)
+        -> bind_back_result_t<deref, Scope*> {
+  // bind_back will try to store a copy of any lvalue references it's passed,
+  // which doesn't work for us here so we have to pass a scope pointer instead
+  // of a scope reference.  we don't, in general, want to expose a
+  // `nest(Sender&&, Scope*)` function so we use `_nest_fn::deref` to do the
+  // indirection for us in this scenario.
+  return bind_back(deref{}, &scope);
+}
+
+}  // namespace _nest_cpo
+
+using _nest_cpo::nest;
+
+}  // namespace unifex
+
+#include <unifex/detail/epilogue.hpp>