c++: implement [[gnu::no_dangling]] [PR110358]

Since -Wdangling-reference has false positives that can't be
prevented, we should offer an easy way to suppress the warning.
Currently, that is only possible by using a #pragma, either around the
enclosing class or around the call site.  But #pragma GCC diagnostic tend
to be onerous.  A better solution would be to have an attribute.

To that end, this patch adds a new attribute, [[gnu::no_dangling]].
This attribute takes an optional bool argument to support cases like:

  template <typename T>
  struct [[gnu::no_dangling(std::is_reference_v<T>)]] S {
     // ...
  };

	PR c++/110358
	PR c++/109642

gcc/cp/ChangeLog:

	* call.cc (no_dangling_p): New.
	(reference_like_class_p): Use it.
	(do_warn_dangling_reference): Use it.  Don't warn when the function
	or its enclosing class has attribute gnu::no_dangling.
	* tree.cc (cxx_gnu_attributes): Add gnu::no_dangling.
	(handle_no_dangling_attribute): New.

gcc/ChangeLog:

	* doc/extend.texi: Document gnu::no_dangling.
	* doc/invoke.texi: Mention that gnu::no_dangling disables
	-Wdangling-reference.

gcc/testsuite/ChangeLog:

	* g++.dg/ext/attr-no-dangling1.C: New test.
	* g++.dg/ext/attr-no-dangling2.C: New test.
	* g++.dg/ext/attr-no-dangling3.C: New test.
	* g++.dg/ext/attr-no-dangling4.C: New test.
	* g++.dg/ext/attr-no-dangling5.C: New test.
	* g++.dg/ext/attr-no-dangling6.C: New test.
	* g++.dg/ext/attr-no-dangling7.C: New test.
	* g++.dg/ext/attr-no-dangling8.C: New test.
	* g++.dg/ext/attr-no-dangling9.C: New test.

2 files changed, 54 insertions, 0 deletions

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 6c2c7ae..f679c81 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -29327,6 +29327,54 @@ Some_Class  B  __attribute__ ((init_priority (543)));
 Note that the particular values of @var{priority} do not matter; only their
 relative ordering.
 
+@cindex @code{no_dangling} type attribute
+@cindex @code{no_dangling} function attribute
+@item no_dangling
+
+This attribute can be applied on a class type, function, or member
+function.  Dangling references to classes marked with this attribute
+will have the @option{-Wdangling-reference} diagnostic suppressed; so
+will references returned from the @code{gnu::no_dangling}-marked
+functions.  For example:
+
+@smallexample
+class [[gnu::no_dangling]] S @{ @dots{} @};
+@end smallexample
+
+Or:
+
+@smallexample
+class A @{
+  int *p;
+  [[gnu::no_dangling]] int &foo() @{ return *p; @}
+@};
+
+[[gnu::no_dangling]] const int &
+foo (const int &i)
+@{
+  @dots{}
+@}
+@end smallexample
+
+This attribute takes an optional argument, which must be an expression that
+evaluates to true or false:
+
+@smallexample
+template <typename T>
+struct [[gnu::no_dangling(std::is_reference_v<T>)]] S @{
+  @dots{}
+@};
+@end smallexample
+
+Or:
+
+@smallexample
+template <typename T>
+[[gnu::no_dangling(std::is_reference_v<T>)]] int& foo (T& t) @{
+  @dots{}
+@};
+@end smallexample
+
 @cindex @code{warn_unused} type attribute
 @item warn_unused
 
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index dc5fd86..bdf05be 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -3908,6 +3908,9 @@ const T& foo (const T&) @{ @dots{} @}
 #pragma GCC diagnostic pop
 @end smallexample
 
+The @code{#pragma} can also surround the class; in that case, the warning
+will be disabled for all the member functions.
+
 @option{-Wdangling-reference} also warns about code like
 
 @smallexample
@@ -3932,6 +3935,9 @@ struct Span @{
 as @code{std::span}-like; that is, the class is a non-union class
 that has a pointer data member and a trivial destructor.
 
+The warning can be disabled by using the @code{gnu::no_dangling} attribute
+(@pxref{C++ Attributes}).
+
 This warning is enabled by @option{-Wall}.
 
 @opindex Wdelete-non-virtual-dtor