[clang] [llvm] [Coroutines] Introduce [[clang::coro_only_destroy_when_complete]] (PR #71014)

[Erich Keane via cfe-commits]

================
@@ -7416,3 +7416,69 @@ that ``p->array`` must have at least ``p->count`` number of elements available:
 
   }];
 }
+
+def CoroOnlyDestroyWhenCompleteDocs : Documentation {
+  let Category = DocCatDecl;
+  let Content = [{
+The `coro_only_destroy_when_complete` attribute should be marked on a C++ class. The coroutines
+whose return type is marked as the attribute are assumed to be destroyed only after then coroutines
+reached to the final suspend point.
+
+This is helpful for the optimizers to perform more optimizations.
+
+For example,
+
+.. code-block:: c++
+
+  A foo() {
+    dtor d;
+    co_await something();
+    dtor d1;
+    co_await something();
+    dtor d2;
+    co_return 43;
+  }
+
+The compiler may generate the following pseudocode:
+
+.. code-block:: c++
+
+  void foo.destroy(foo.Frame *frame) {
+    switch(frame->suspend_index()) {
+      case 1:
+        frame->d.~dtor();
+        break;
+      case 2:
+        frame->d.~dtor();
+        frame->d1.~dtor();
+        break;
+      case 3:
+        frame->d.~dtor();
+        frame->d1.~dtor();
+        frame->d2.~dtor();
+        break;
+      default: // coroutine completed or haven't started
+        break;
+    }
+
+    frame->promise.~promise_type();
+    delete frame;
+  }
+
----------------
erichkeane wrote:

For the section below, how about:

```
The `foo.destroy()` function's purpose is to release all of the resources initialized for the coroutine when it is destroyed in a suspended state.  However, if the coroutine is only ever destroyed at the final suspend state, the rest of the conditions are superfluous. The user can use the `coro_only_destroy_when_complete` attributo suppress generation of the other destruction cases, optimizing the above `foo.destroy` to:
```

https://github.com/llvm/llvm-project/pull/71014