result/rich_error.h

Summary: # Diff stack context in D89023323

Reviewed By: ispeters

Differential Revision: D89023195

fbshipit-source-id: 904d0b57345cd50d6288aa2630f6f3992f64076b

Author: snarkmaster

third-party/folly/src/folly/result/detail/rich_error_common.h

@@ -0,0 +1,122 @@
+/*
+ * 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/Portability.h> // FOLLY_HAS_RESULT
+#include <folly/Traits.h>
+#include <folly/lang/Pretty.h>
+#include <folly/result/rich_error_base.h>
+
+// Shared details for `rich_error.h` and `immortal_rich_error.h`.
+
+#if FOLLY_HAS_RESULT
+
+namespace folly::detail {
+
+template <typename T>
+struct rich_error_add_partial_message_impl : public T {
+  using T::T;
+  constexpr const char* partial_message() const noexcept override {
+    return pretty_name<T>();
+  }
+};
+
+// Non-abstract only if `T` implements `partial_message()`
+template <typename T>
+class rich_error_test_for_partial_message : T {
+ private:
+  rich_error_test_for_partial_message() = delete; // don't construct or inherit
+  void only_rich_error_may_instantiate(
+      rich_error_base::only_rich_error_may_instantiate_t) override {}
+};
+
+// Adds `partial_message() only if `T` doesn't provide it.
+//
+// Design rationale: There are two reasonable ideas for having `rich_error<>`
+// and `immortal_rich_error<>` automatically add in a simple `partial_message`
+// if it's not already supplied:
+//
+//   - The current one.  It has the downside of making the class hierarchy
+//     deeper for errors that don't implement their own.  This in turn can slow
+//     down `dynamic_cast` (when our RTTI-free optimizations don't apply, see
+//     `rich_exception_ptr_bench.cpp`).  However, in practice, production
+//     errors should likely define a better message anyhow, so this is fine.
+//
+//   - Have the leaf classes always define `partial_message()`, and internally
+//     delegate via `if constexpr ()` to the base if it has one.  This one is
+//     also ok, but it adds code size for ALL error types, unconditionally.
+template <typename T>
+using rich_error_with_partial_message = conditional_t<
+    !std::is_abstract_v<rich_error_test_for_partial_message<T>>,
+    T,
+    rich_error_add_partial_message_impl<T>>;
+
+// Validate a user-defined "rich error" class `Ex` while instantiating
+// `rich_error<Ex>` or `immortal_rich_error<Ex>`.
+//
+// Thanks to the `rich_error_base` passkey, a user should not be able to
+// instantiate such an `Ex` directly, so this provides pretty good guarantees
+// that `Ex*` can only be obtained from `...rich_error<Ex>`, and thus has
+// passed these validations.
+//
+// Why isn't this a concept contraining class templates? Two reasons:
+//   - A constraint prevents referencing `rich_error<A>` from `A`.
+//   - Forward-declarations get messier.
+//
+// Future: Most user types for `rich_error` should **NOT** inherit from
+// `std::exception`, since the leaf wrappers will add it to the dynamic type.
+// But, we cannot uniformly enforce this since there are valid uses that do
+// need it on the base.  If the issue of "accidentally adding an
+// `std::exception` diamond" is both common and problematic, we could either:
+//   - Change `rich_error` to only add it if it's not already there.
+//   - Ban it by default and add an API to bypass that check.
+//
+// `require_sizeof` since some checks are UB with incomplete types
+template <
+    typename UserEx,
+    std::derived_from<UserEx> ActualEx, // rich_error<> or immortal...storage<>
+    size_t = require_sizeof<UserEx>>
+inline constexpr bool static_assert_is_valid_rich_error_type(const ActualEx*) {
+  static_assert(
+      std::derived_from<UserEx, rich_error_base>,
+      "Rich error types must derive from `rich_error_base`.");
+  // Without the offset-0 property, it would be UB to do the RTTI-free
+  // `rich_error_base` access, as implemented by `rich_exception_ptr`.
+  static_assert(
+      detail::has_offset0_base<ActualEx, rich_error_base>,
+      "When inheriting from `rich_error_base`, that type (or its derived type) "
+      "must be first in the inheritance list.");
+  // Did the user type correctly use `rich_error_hints`?
+  //
+  // Future: If you have a strong case for NOT hinting a base error class in
+  // its own definition, add a bypass for the "each type must hint at least
+  // itself" rich error static assert.  The bypass can simply be a
+  // `folly_`-prefixed member type alias that points to the current class, e.g.
+  //   struct UnhintedBase : rich_error_base {
+  //     using folly_rich_error_do_not_require_hint_for = UnhintedBase;
+  //   };
+  using Hint = typename UserEx::folly_get_exception_hint_types;
+  static_assert(
+      type_list_find_v<rich_error<UserEx>, Hint> < type_list_size_v<Hint>,
+      "A rich error user type `T` should use `rich_error_hints<T>` to avoid "
+      "RTTI costs. If this is a base class, read the 'hints' docblock.");
+  return true;
+}
+
+} // namespace folly::detail
+
+#endif // FOLLY_HAS_RESULT

third-party/folly/src/folly/result/rich_error.h

@@ -0,0 +1,88 @@
+/*
+ * 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/Portability.h> // FOLLY_HAS_RESULT
+#include <folly/lang/Exception.h>
+#include <folly/lang/Pretty.h>
+#include <folly/result/detail/rich_error_common.h>
+#include <folly/result/rich_error_fwd.h>
+
+#if FOLLY_HAS_RESULT
+
+/// See: docs/rich_error.md
+
+namespace folly {
+
+/// Syntax sugar for `folly::get_exception<rich_error_base>()`.
+///
+/// This retrieves the **underlying** rich error.  `enriching_errors.md`
+/// describes this in detail, but in brief:
+///   - Enrichment only works with `folly/result/` error containers.
+///   - If the underlying error is not a `rich_error_base`, you will get back
+///     null, **even if** it was later enriched.
+///   - Furthermore, if you used `enrich_non_value()` or another enriching
+///     wrapper, `->partial_message()` will NOT give you the enrichment
+///     message, but the rather the one from the base rich error.
+///
+/// Very rarely, you may want `get_outer_exception` to access the enrichment
+/// wrapper object itself.
+inline constexpr get_exception_fn<rich_error_base> get_rich_error{};
+
+// See: docs/rich_error.md
+template <typename UserBase> // must derive from `rich_error_base`
+class rich_error final
+    : public detail::rich_error_with_partial_message<UserBase>,
+      public std::exception {
+ private:
+  using Base = detail::rich_error_with_partial_message<UserBase>;
+
+  void only_rich_error_may_instantiate(
+      rich_error_base::only_rich_error_may_instantiate_t) override {}
+
+ public:
+  const char* what() const noexcept override {
+    // These assertions are under `what()` since this virtual member **must** be
+    // instantiated together with the class template. Has a manual test.
+    detail::static_assert_is_valid_rich_error_type<UserBase>(this);
+    auto msg = Base::partial_message();
+    return msg[0] ? msg : pretty_name<rich_error>();
+  }
+
+  rich_error() = default;
+
+  // Delegate non-standard ctors to the user-defined `Base`
+  template <typename T, typename... Ts>
+    requires(
+        !std::is_same_v<rich_error, std::remove_cvref_t<T>> &&
+        !std::is_same_v<detail::immortal_rich_error_private_t, T>)
+  explicit rich_error(T&& t, Ts&&... ts)
+      : Base{static_cast<T&&>(t), static_cast<Ts&&>(ts)...} {}
+
+  rich_error(detail::immortal_rich_error_private_t, const Base& that)
+      : Base{that} {}
+
+  // This isn't `Base` because `immortal_rich_error` will wrap it again.
+  using folly_detail_base_of_rich_error = UserBase;
+  // NB: This hint is a no-op, unless `UserBase` declares one, in which case
+  // this just prevents the use of the wrong hint.
+  using folly_get_exception_hint_types = tag_t<rich_error>;
+};
+
+} // namespace folly
+
+#endif // FOLLY_HAS_RESULT

third-party/folly/src/folly/result/test/common.h

@@ -20,10 +20,41 @@
 #include <string>
 
 #include <folly/Benchmark.h>
+#include <folly/portability/GMock.h>
 #include <folly/portability/GTest.h>
+#include <folly/result/rich_exception_ptr.h>
 
 namespace folly {
 
+constexpr void test(bool cond) {
+  if (!cond) {
+    // NOLINTNEXTLINE(facebook-hte-ThrowNonStdExceptionIssue)
+    throw "test failed";
+  }
+}
+
+namespace detail { // Some tests are defined in `detail`...
+using folly::test;
+} // namespace detail
+
+void checkFormat(const auto& err, const std::string& re) {
+  EXPECT_THAT(fmt::format("{}", err), ::testing::MatchesRegex(re));
+  std::stringstream ss;
+  ss << err;
+  EXPECT_THAT(ss.str(), ::testing::MatchesRegex(re));
+}
+
+template <typename... Queries>
+void checkFormatViaGet(const auto& container, const std::string& re) {
+  (checkFormat(get_exception<Queries>(container), re), ...);
+}
+
+template <typename... Queries>
+void checkFormatOfErrAndRep(const auto& err, const std::string& re) {
+  checkFormat(err, re);
+  checkFormatViaGet<Queries...>(rich_exception_ptr{err}, re);
+}
+
 // Helper to run benchmarks as a smoke test with minimal iterations.
 // A "benchmarks don't crash" test is meaningful (1) since the benchmarks
 // actually run some basic assertions, (2) CI will run this under ASAN.