co_ready for unpacking result<T> values in async coros

Summary: Together with `co_await_result` & pre-existing `co_result`, this gives easy interop between sync `result<T>` coroutines and async ones like `Task<T>`.

Reviewed By: ispeters

Differential Revision: D71762048

fbshipit-source-id: abf9a797aa1565c5b80ac4b12825fb0c1d51ceac

Author: snarkmaster

folly/coro/Ready.h

@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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 <folly/Executor.h>
+#include <folly/coro/Result.h>
+#include <folly/coro/WithAsyncStack.h>
+
+/// Use `co_ready` to "await" synchronous coroutine types from inside async
+/// coroutines like `coro::Task`. For example:
+///
+///   result<int> getN();
+///   int n = co_await co_ready(getN());
+///
+/// Also see `co_await_result` (`AwaitResult.h`) and `co_result` (`Result.h`).
+///
+/// If you need to optimize away ALL exception throwing in **async** code,
+/// `co_ready` is not your top choice.  In a `Task` coro:
+///
+///   auto v = co_await co_nothrow(asyncMayError()); // best practice
+///   auto v = co_await co_ready(co_await_result(asyncMayError())); // too long
+///
+/// However, when you are calling synchronous `result` functions, or need to
+/// efficiently handle **some** async errors, `co_ready` is your friend:
+///
+///   auto res = syncResultFn(); // or `co_await co_await_result(asyncFn())`
+///   if (auto* ex = get_exception<MyError>(res)) {
+///     /* handle ex */
+///   } else {
+///     auto v = co_await co_ready(std::move(res)); // propagate unhandled
+///   }
+///
+/// This pattern has a few good properties:
+///   - Easy error handling -- extracts the value from its argument, or
+///     short-circuit any error to current coro's awaiter.
+///   - Unlike `catch (const std::exception& ex)`, won't catch (and therefore
+///     break) cancellation.
+///   - The error path is MUCH more efficient (3-30 nanoseconds) than
+///     `value_or_throw()` (1 microsecond).
+///
+/// We don't support `co_await syncResultFn()` to avoids confusion about which
+/// parts of the code are sync vs async.  The distinction is critical, since
+/// one must not hold non-coro mutexes across async suspend points.
+///
+/// Future:
+///   - Adding `std::ref` / `std::cref`, and possibly `folly::rref` variants of
+///     this (as in `result.h`) might improve performance in hot code.
+///   - The current implementation is `result`-only.  If you have a need, it
+///     would be fine to add the analogous specialization for `Try`.  Just be
+///     mindful of its two warts: empty state and empty `exception_wrapper`.
+
+namespace folly::coro {
+
+template <typename>
+class co_ready;
+
+#if FOLLY_HAS_RESULT
+
+template <typename T>
+class co_ready<result<T>> {
+ private:
+  result<T> res_;
+
+ public:
+  explicit co_ready(result<T>&& res) : res_(std::move(res)) {}
+
+  bool await_ready() const noexcept { return res_.has_value(); }
+
+  auto await_resume() noexcept -> decltype(std::move(res_).value_or_throw()) {
+    return std::move(res_).value_or_throw();
+  }
+
+  template <typename Promise>
+  auto await_suspend(
+      std::coroutine_handle<Promise> awaitingCoroutine) noexcept {
+    auto& promise = awaitingCoroutine.promise();
+    // We have to use the legacy API because (1) `folly::coro` internals still
+    // model cancellation as an exception, (2) to use `co_cancelled` here we'd
+    // have to check `res_` for `OperationCancelled` which can cost 50-100ns+.
+    auto awaiter = promise.yield_value(co_error(
+        std::move(res_).non_value().get_legacy_error_or_cancellation()));
+    return awaiter.await_suspend(awaitingCoroutine);
+  }
+
+  friend auto co_viaIfAsync(
+      const Executor::KeepAlive<>&, co_ready&& r) noexcept {
+    return std::move(r);
+  }
+
+  friend auto tag_invoke(cpo_t<co_withAsyncStack>, co_ready&& r) noexcept {
+    return std::move(r);
+  }
+};
+
+template <typename T>
+co_ready(result<T>&&) -> co_ready<result<T>>;
+
+#endif // FOLLY_HAS_RESULT
+
+} // namespace folly::coro

folly/coro/test/ReadyTest.cpp

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ */
+
+#include <folly/coro/AwaitResult.h>
+#include <folly/coro/GtestHelpers.h>
+#include <folly/coro/Ready.h>
+#include <folly/coro/safe/NowTask.h>
+
+#if FOLLY_HAS_RESULT
+
+namespace folly::coro {
+
+CO_TEST(ReadyTest, co_ready_of_error_result) {
+  auto errorTaskFn = []() -> NowTask<> {
+    result<> res = make_exception_wrapper<std::runtime_error>("foo");
+    try {
+      co_await co_ready(std::move(res));
+    } catch (...) {
+    } // propagates exception WITHOUT rethrowing
+    LOG(FATAL) << "not reached";
+  };
+  auto res = co_await co_await_result(errorTaskFn());
+  EXPECT_STREQ("foo", get_exception<std::runtime_error>(res)->what());
+}
+
+CO_TEST(ReadyTest, co_ready_of_value_result) {
+  auto valueTaskFn = []() -> NowTask<int> {
+    result res = 1300;
+    co_return 37 + co_await co_ready(std::move(res));
+  };
+  EXPECT_EQ(1337, co_await valueTaskFn());
+
+  // Use a move-only value to check we don't have extraneous copies
+  auto moveValueTaskFn = []() -> NowTask<std::unique_ptr<int>> {
+    result res = std::make_unique<int>(1300);
+    auto np = co_await co_ready(std::move(res));
+    *np += 37;
+    co_return std::move(np);
+  };
+  EXPECT_EQ(1337, *(co_await moveValueTaskFn()));
+}
+
+CO_TEST(ReadyTest, co_ready_of_void_result) {
+  auto taskFn = [&]() -> NowTask<int> {
+    result<> res;
+    co_await co_ready(std::move(res));
+    co_return 42;
+  };
+  EXPECT_EQ(42, co_await taskFn());
+}
+
+CO_TEST(ReadyTest, co_ready_stopped) {
+  auto taskFn = [&]() -> NowTask<int> {
+    result<> res = stopped_result;
+    co_await co_ready(std::move(res));
+    co_return 42;
+  };
+  EXPECT_TRUE((co_await co_await_result(taskFn())).has_stopped());
+}
+
+} // namespace folly::coro
+
+#endif