[LLVM][Support] add nonNull function helper (llvm#188718)

We often see a pattern like:
```
T *ptr = doSomething()
assert(ptr && "doSomething() shouldn't return nullptr");
```

We also have functions like `cantFail`, but those are working with
Expected types.
This commits adds a `nonNull` function, which can be used inline. In
practice, one could use:

```
T *ptr = cast<T>(functionReturningT());
```

But it conveys the meaning that `functionReturningT` might return a
subtype/supertype that we actually cast.

Function behaves like the other error kinds: calls llvm_unreachable,
which may or may not trap depending on the build options. Calling this
function with `nullptr` won't build, but it makes no sense to do so.

---------

Co-authored-by: Jakub Kuderski <kubakuderski@gmail.com>

Author: Keenuts

llvm/docs/ProgrammersManual.rst

@@ -453,6 +453,15 @@ violations even in builds that do not enable assertions:
     reportFatalInternalError("Analysis 'foo' not preserved");
   }
 
+Additionally, ``checkNotNull`` can be used to check/document that a pointer
+is never supposed to be null inline.
+
+.. code-block:: c++
+
+    setMyPointer("key", Pointer);
+    // [...]
+    Type *P = checkNotNull(getMyPointer("key"));
+
 Recoverable Errors
 ^^^^^^^^^^^^^^^^^^
 

llvm/include/llvm/Support/Error.h

@@ -811,6 +811,29 @@ T cantFail(Expected<T> ValOrErr, const char *Msg = nullptr) {
   }
 }
 
+namespace detail {
+
+template <typename T>
+using compare_nullptr_t = decltype(std::declval<T &>() == nullptr);
+
+template <typename T>
+using is_nullptr_comparable = llvm::is_detected<compare_nullptr_t, T>;
+
+} // namespace detail
+
+/// Calls llvm_unreachable if Pointer is null, otherwise returns the
+/// pointer as is.
+template <typename T,
+          typename = std::enable_if_t<detail::is_nullptr_comparable<T>::value>>
+[[nodiscard]] decltype(auto) checkNotNull(
+    T &&Pointer,
+    const char *Msg = "Expected a non-null pointer but got a null pointer") {
+  assert(Msg);
+  if (Pointer != nullptr)
+    return std::forward<T>(Pointer);
+  llvm_unreachable(Msg);
+}
+
 /// Report a fatal error if ValOrErr is a failure value, otherwise unwraps and
 /// returns the contained reference.
 ///

llvm/unittests/Support/ErrorTest.cpp

@@ -1219,4 +1219,42 @@ TEST(Error, ForwardToExpected) {
   EXPECT_THAT_ERROR(ExpectedReturningFct(false).moveInto(MaybeV), Succeeded());
   EXPECT_EQ(*MaybeV, 42);
 }
+
+TEST(Error, NonNullSuccess) {
+  int tmp = 0;
+  int *ptr = &tmp;
+  const int *cptr = ptr;
+  const int *const ccptr = ptr;
+  auto uptr = std::make_unique<int>(0);
+
+  EXPECT_EQ(ptr, checkNotNull(&tmp));
+  EXPECT_EQ(ptr, checkNotNull(ptr));
+  EXPECT_EQ(ptr, checkNotNull(cptr));
+  EXPECT_EQ(ptr, checkNotNull(ccptr));
+  EXPECT_EQ(uptr, checkNotNull(std::move(uptr)));
+}
+
+#if !defined(NDEBUG) && GTEST_HAS_DEATH_TEST
+TEST(Error, NonNullFails) {
+  int *NullPtr = nullptr;
+  EXPECT_DEATH(NullPtr = checkNotNull(NullPtr),
+               "Expected a non-null pointer but got a null pointer")
+      << "checkNotNull(NullPtr) did not cause an abort for null pointer";
+
+  EXPECT_DEATH(NullPtr = checkNotNull(nullptr),
+               "Expected a non-null pointer but got a null pointer")
+      << "checkNotNull(NullPtr) did not cause an abort for null pointer";
+
+  auto UniquePtr = std::make_unique<int>(0);
+  UniquePtr.release();
+  EXPECT_DEATH(auto TmpUniquePtr = checkNotNull(std::move(UniquePtr)),
+               "Expected a non-null pointer but got a null pointer")
+      << "checkNotNull(NullPtr) did not cause an abort for null pointer";
+
+  EXPECT_DEATH(NullPtr = checkNotNull(NullPtr, "custom message"),
+               "custom message")
+      << "checkNotNull(nullptr) did not cause an abort for null pointer";
+}
+#endif
+
 } // namespace