result<T>: value-or-exception_wrapper type & short-circuiting coro

Summary:
## Pitch for "working programmers"

`result<T>` is a more ergonomic, safer `Try<T>` replacement for code that, for reasons of performance or reliability, chooses to explicitly propagate errors via `return`.

Consider this "idiomatic `Try` code":

```cpp
// Bug farm: what if this accidentally throws?
Try<int> mayFail() { ... }

Try<float> alsoFallible() {
  Try<int> tryN = mayFail();
  float v = 5.0;
  if (tryN.hasValue()) {
    v += *tryN;
  } else if (tryN.hasError()) {
    return Try<float>(tryN.error());
  } else {
    // This bug is easy to make, since `Try` default-constructs as empty!
    LOG(DFATAL) << "BUG: `mayFail()` returned an empty Try";
  }
  return Try<float>(v);
}
```

With `result`, both potential bugs are prevented, and the code is *just* business logic:
  -  "What if `mayFail()` accidentally throws?" is a non-issue since `alsoFallible()` is a `result` coroutine, and thus automatically wraps any uncaught exceptions.
  - "Empty `Try`" bugs go away since `result` is almost-never-empty [*]

```cpp
result<int> mayFail() { ... }

result<float> alsoFallible() {
  co_return 5.0 + co_await mayFail();
}
```

[*] Until we have `std::expected` in C++23, `result<T>` is implemented via `folly::Expected<T, exception_wrapper>`, which is merely "almost-never-empty", rather than "never empty".  That said, you will be hard-pressed to hit the empty state with well-formed types -- I tried and failed to construct one naturally in `result_test.cpp` (and settled for "synthetic" objects in an empty state). If you **do** manage hit the empty state, the `result` accessors are carefully crafted to degrade gracefully, so the end user really doesn't have to test for it.

 ---

## Cancellation -- library-author considerations

Looking ahead to C++26 and [P2300](https://wg21.link/p2300), note that receivers have 3 completion states: value/error/stopped. In `folly::coro`, the latter 2 are fused -- cancelled tasks finish with  exception `OperationCancelled`. On the other hand, [P2300](https://wg21.link/p2300) takes pains to separate them. That thinking derives from [P1677](https://wg21.link/p1677). The central "working programmer" problem that "cancellation is not an exception" tries to address is, in paraphrase:

> "Child stopped" should NOT be handled by exception catch-alls, since a higher-level orchestrator decided the work is no longer needed.

The right behavior is to free the resources from this tree of execution as quickly as possible. So, by letting "stopped" state bypass regular exception-handling, [P1677](https://wg21.link/p1677) / [P2300](https://wg21.link/p2300) aim to prevent the class of bugs where cancellation gets accidentally caught and "handled".

Today's users of `folly` expect only 2 states: value & error (possibly `OperationCancelled`). Since `result` is a new API, this stack takes the opportunity to add some forward-compatibility.

First, D72181807 and D72074521 take some steps to discourage the use of raw `OperationCancelled` by end-users -- `result` is one of the suggested solutions.

Second, the top-level `result<T>` API is sort-of bi-state -- it exposes only `has_value()` as a primary test. The "error" and "stopped" state are deliberately hidden in a `non_value()` sub-structure. Yes, `result` also has `has_stopped()`, but that's just shorthand for `!has_value() && non_value().has_stopped()`.

This two-level design works quite well to reconcile the goals of "good UX today" and "forward-compatibility with value/error/stopped semantics":
  - Getting values is easy & safe -- `co_await ...` / `co_await coro::co_ready(...)`. These recommended idioms auto-propagate unhandled errors & cancellation.
  - Testing specific errors is easy & safe -- `get_exception<Ex>(res)`.
  - Manually propagating unhandled errors & cancellation is also easy & safe -- `return std::move(res).non_value()`.

On the other hand, `result` do **not** provide an easy catch-all -- it would be prone to accidentally catching the cancellation exception! Rather, `result` **deliberately** omits `has_error()` or `error()` -- you have to access `non_value()` to get at those, meaning that you're more likely to correctly test `has_stopped()`.

From a user perspective, `result` is `variant<T, variant<stopped, error>>`. However, the implementation is just `Expected<T, exception_wrapper>` -- and it efficiently ingests exceptions from `folly::coro` and `Try`, which don't treat "stopped" separately. Here's how that works:
  - We use `make_legacy_...` and `get_legacy_...` methods to interact with old-school implementations like `folly::coro` & `Try`. These methods expect an `expection_wrapper` which **may** be an `OperationCancelled`.
  - In contrast, using normal **end-user** APIs, debug builds will **terminate** if you store `OperationCancelled` in, or retrieve an `error()` from a stopped-state `result` / `non_value_result`. The error says to use `has_stopped()` and `stopped_result` instead.

Finally, `result` also prohibits `error()` from being an empty `exception_wrapper` -- that unconditionally terminates if you try to re-throw it! This creates some option value -- once we actively go after `OperationCancelled` deprecation, we can potentially co-opt this empty state as a cheap cancellation signal.

Reviewed By: ispeters

Differential Revision: D71522263

fbshipit-source-id: 8ae98c979c61e5cd9a26dfc26fbf86dd36471b3f

Author: snarkmaster

folly/Portability.h

@@ -696,6 +696,15 @@ constexpr auto kCpplibVer = 0;
 #endif
 #endif // FOLLY_CFG_NO_COROUTINES
 
+// It'd be possible to relax this, by refactoring `folly/result` code down to
+// C++17, and by only blocking the coroutine support for non-coro compiles.
+// However, `result<T>` is primarily targeted at newer codebases.
+#if FOLLY_CPLUSPLUS >= 202002L && FOLLY_HAS_COROUTINES
+#define FOLLY_HAS_RESULT 1
+#else
+#define FOLLY_HAS_RESULT 0
+#endif
+
 // C++20 consteval
 #if FOLLY_CPLUSPLUS >= 202002L
 #define FOLLY_CONSTEVAL consteval

folly/lang/Exception.h

@@ -613,8 +613,9 @@ struct get_exception_tag_t {};
 /// This is most efficient when `Ex` matches the exact stored type, or when the
 /// type alias `Ex::folly_get_exception_hint_types` has a good hint.
 ///
-/// NB: `Try<T>` currently omits `get_exception(get_exception_tag_t)`, because
-/// supporting it might encourage "empty state" bugs:
+/// NB: `result<T>` supports `get_exception<Ex>(res)`, but `Try<T>` currently
+/// omits `get_exception(get_exception_tag_t)`, because that might encourage
+/// "empty state" bugs:
 ///
 ///   if (auto* ex = get_exception<MyError>(tryData)) {
 ///     // handle error

folly/result/gtest_helpers.h

@@ -0,0 +1,66 @@
+/*
+ * 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/coro/GtestHelpers.h>
+#include <folly/result/result.h>
+
+namespace folly {
+
+#define RESULT_CO_UNWRAP_BODY(body)                  \
+  {                                                  \
+    auto ret = body();                               \
+    if (!ret.has_value()) {                          \
+      if (ret.non_value().has_error()) {             \
+        FAIL() << ret.non_value().error();           \
+      } else {                                       \
+        FAIL() << "RESULT_CO_TEST got cancellation"; \
+      }                                              \
+    }                                                \
+  }
+
+/*
+Analog of GTest `TEST()` macro for writing `result` coroutine tests.
+
+For assertions, use either standard `EXPECT_*` macros, or `CO_ASSERT_*` from
+`folly/coro/GtestHelpers.h`.
+*/
+#define RESULT_CO_TEST(test_case_name, test_name) \
+  CO_TEST_(                                       \
+      test_case_name,                             \
+      test_name,                                  \
+      ::testing::Test,                            \
+      ::testing::internal::GetTestTypeId(),       \
+      result<>,                                   \
+      RESULT_CO_UNWRAP_BODY)
+
+/*
+Analog of GTest `TEST_F()` macro for writing `result` coroutine tests.
+
+For assertions, use either standard `EXPECT_*` macros, or `CO_ASSERT_*` from
+`folly/coro/GtestHelpers.h`.
+*/
+#define RESULT_CO_TEST_F(test_fixture, test_name)     \
+  CO_TEST_(                                           \
+      test_fixture,                                   \
+      test_name,                                      \
+      test_fixture,                                   \
+      ::testing::internal::GetTypeId<test_fixture>(), \
+      result<>,                                       \
+      RESULT_CO_UNWRAP_BODY)
+
+} // namespace folly

folly/result/result.cpp

@@ -0,0 +1,54 @@
+/*
+ * 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/result/result.h>
+
+#include <glog/logging.h>
+#include <folly/Indestructible.h>
+
+#if FOLLY_HAS_RESULT
+
+namespace folly::detail {
+
+const non_value_result& dfatal_get_empty_result_error() {
+  static const folly::Indestructible<non_value_result> r{
+      make_exception_wrapper<empty_result_error>()};
+  LOG(DFATAL) << "`folly::result` had an empty underlying `folly::Expected`";
+  return *r;
+}
+
+const non_value_result& dfatal_get_bad_result_access_error() {
+  static const folly::Indestructible<non_value_result> r{
+      make_exception_wrapper<bad_result_access_error>()};
+  LOG(DFATAL) << "Used `error()` accessor for `folly::result` in value state";
+  return *r;
+}
+
+void fatal_if_exception_wrapper_invalid(const exception_wrapper& ew) {
+  if (!ew.has_exception_ptr()) {
+    LOG(FATAL) << "`result` may not contain an empty `exception_wrapper`";
+  }
+  if (folly::get_exception<folly::OperationCancelled>(ew)) {
+    LOG(FATAL)
+        << "Do not put `OperationCancelled` in `result`, or get it via "
+        << "`error()`. Instead, store `stopped_result{}`, and check "
+        << "`has_error()` (or `!has_stopped()`) before calling `error()`.";
+  }
+}
+
+} // namespace folly::detail
+
+#endif // FOLLY_HAS_RESULT