On 2/2/24 02:09, Andi Kleen wrote:
gcc/ChangeLog:
* doc/extend.texi: Document [[musttail]]
---
gcc/doc/extend.texi | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 142e41ab8fbf..866f6c4a9fed 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9875,6 +9875,22 @@ foo (int x, int y)
@code{y} is not actually incremented and the compiler can but does not
have to optimize it to just @code{return 42 + 42;}.
+@cindex @code{musttail} statement attribute
+@item musttail
+
+The @code{gnu::musttail} or @code{clang::musttail} attribute
+can be applied to a return statement that returns the value
+of a call to indicate that the call must be a tail call
+that does not allocate extra stack space.
It took me about 3 attempts to parse this. :-S I think this might be a
little better:
...can be applied to a @code{return} statement with a return-value
expression that is a function call. It asserts that the call must be a
tail call that does not allocate extra stack space.
+
+@smallexample
+[[gnu::musttail]] return foo();
+@end smallexample
+
+If the compiler cannot generate a tail call it will generate
s/will generate/generates/
I'm a big fan of writing in the present tense. ;-)
+an error. Tail calls generally require enabling optimization.
+On some targets they may not be supported.
+
@end table
@node Attribute Syntax
In addition to these changes, at the beginning of this section we have
@node Statement Attributes
@section Statement Attributes
@cindex Statement Attributes
GCC allows attributes to be set on null statements. @xref{Attribute
Syntax},
for details of the exact syntax for using attributes. [...]
Well, we now have an attribute that goes on a non-null statement, so we
have to fix this. The documentation for the other statement attributes
is already explicit that they go on null statements so those already
would be OK if we just removed the "null" restriction here. OTOH, the
Attribute Syntax section, in discussing GCC's traditional attribute
syntax, says:
@subsubheading Statement Attributes
In GNU C, an attribute specifier list may appear as part of a null
statement. The attribute goes before the semicolon.
If "musttail" is only supported in the standard attribute syntax, its
new entry in the Statement Attributes node must say that, and the blurb
at the top of the node quoted above must say something to the effect
that the traditional syntax only allows statement attributes on null
statements and attributes on non-null statements are only permitted in
the new standard attribute form.
-Sandra
