Add documentation and simplify test

Author: dmpolukhin

clang-tools-extra/docs/ReleaseNotes.rst

@@ -183,7 +183,7 @@ Changes in existing checks
   explicit casting of built-in types within member list initialization.
 
 - Improved :doc:`modernize-use-ranges
-  <clang-tidy/checks/modernize/use-ranges>` check by updating suppress 
+  <clang-tidy/checks/modernize/use-ranges>` check by updating suppress
   warnings logic for ``nullptr`` in ``std::find``.
 
 - Improved :doc:`modernize-use-starts-ends-with
@@ -203,6 +203,8 @@ Changes in existing checks
   <clang-tidy/checks/performance/unnecessary-value-param>` check performance by
   tolerating fix-it breaking compilation when functions is used as pointers
   to avoid matching usage of functions within the current compilation unit.
+  Also suppressed this check for coroutine functions because it may not be safe
+  and suggested fixes may result in hard-to-find bugs and crashes.
 
 Removed checks
 ^^^^^^^^^^^^^^

clang-tools-extra/docs/clang-tidy/checks/performance/unnecessary-value-param.rst

@@ -18,6 +18,10 @@ the following heuristic is employed:
    on it, or it is used as const reference or value argument in constructors or
    function calls.
 
+Note: This check does not suggest passing parameters by reference in coroutines
+because, after a coroutine suspend point, references could be dangling and no
+longer valid, so suggested changes may result in hard-to-find bugs and crashes.
+
 Example:
 
 .. code-block:: c++

clang-tools-extra/test/clang-tidy/checkers/performance/unnecessary-value-param-coroutine.cpp

@@ -2,59 +2,32 @@
 
 namespace std {
 
-template <typename R, typename...> struct coroutine_traits {
-  using promise_type = typename R::promise_type;
+template <class Ret, typename... T> struct coroutine_traits {
+  using promise_type = typename Ret::promise_type;
 };
 
-template <typename Promise = void> struct coroutine_handle;
-
-template <> struct coroutine_handle<void> {
-  static coroutine_handle from_address(void *addr) noexcept {
-    coroutine_handle me;
-    me.ptr = addr;
-    return me;
-  }
-  void operator()() { resume(); }
-  void *address() const noexcept { return ptr; }
-  void resume() const {  }
-  void destroy() const { }
-  bool done() const { return true; }
-  coroutine_handle &operator=(decltype(nullptr)) {
-    ptr = nullptr;
-    return *this;
-  }
-  coroutine_handle(decltype(nullptr)) : ptr(nullptr) {}
-  coroutine_handle() : ptr(nullptr) {}
-  //  void reset() { ptr = nullptr; } // add to P0057?
-  explicit operator bool() const { return ptr; }
-
-protected:
-  void *ptr;
+template <class Promise = void> struct coroutine_handle {
+  static coroutine_handle from_address(void *) noexcept;
+  static coroutine_handle from_promise(Promise &promise);
+  constexpr void *address() const noexcept;
 };
 
-template <typename Promise> struct coroutine_handle : coroutine_handle<> {
-  using coroutine_handle<>::operator=;
-
-  static coroutine_handle from_address(void *addr) noexcept {
-    coroutine_handle me;
-    me.ptr = addr;
-    return me;
-  }
-
-  Promise &promise() const {
-    return *reinterpret_cast<Promise *>(
-        __builtin_coro_promise(ptr, alignof(Promise), false));
-  }
-  static coroutine_handle from_promise(Promise &promise) {
-    coroutine_handle p;
-    p.ptr = __builtin_coro_promise(&promise, alignof(Promise), true);
-    return p;
-  }
+template <> struct coroutine_handle<void> {
+  template <class PromiseType>
+  coroutine_handle(coroutine_handle<PromiseType>) noexcept;
+  static coroutine_handle from_address(void *);
+  constexpr void *address() const noexcept;
 };
 
 struct suspend_always {
   bool await_ready() noexcept { return false; }
-  void await_suspend(std::coroutine_handle<>) noexcept {}
+  void await_suspend(coroutine_handle<>) noexcept {}
+  void await_resume() noexcept {}
+};
+
+struct suspend_never {
+  bool await_ready() noexcept { return true; }
+  void await_suspend(coroutine_handle<>) noexcept {}
   void await_resume() noexcept {}
 };