https://gcc.gnu.org/g:26e9139691ac73f53fad64960a0ea48830adfa52
commit r15-9185-g26e9139691ac73f53fad64960a0ea48830adfa52
Author: Sandra Loosemore <sloosem...@baylibre.com>
Date: Thu Apr 3 05:02:34 2025 +0000
Doc: Clean up musttail attribute docs some more
Looking over the recently-committed change to the musttail attribute
documentation, it appears the comment in the last example was a paste-o,
as it does not agree with either what the similar example in the
-Wmaybe-musttail-local-addr documentation says, or the actual behavior
observed when running the code.
In addition, the entire section on musttail was in need of copy-editing
to put it in the present tense, avoid reference to "the user", etc. I've
attempted to clean it up here.
gcc/ChangeLog
* doc/extend.texi (Statement Attributes): Copy-edit the musttail
attribute documentation and correct the comment in the last
example.
Diff:
---
gcc/doc/extend.texi | 46 +++++++++++++++++++++++-----------------------
1 file changed, 23 insertions(+), 23 deletions(-)
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 4302df76c7fa..16ad83fc510c 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9314,7 +9314,7 @@ The @code{gnu::musttail} or @code{clang::musttail}
standard attribute
or @code{musttail} GNU attribute 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, so it is
-safe to use tail recursion to implement long running loops.
+safe to use tail recursion to implement long-running loops.
@smallexample
[[gnu::musttail]] return foo();
@@ -9324,11 +9324,11 @@ safe to use tail recursion to implement long running
loops.
__attribute__((musttail)) return bar();
@end smallexample
-If the compiler cannot generate a @code{musttail} tail call it will report
-an error. On some targets tail calls may never be supported.
-The user asserts for @code{musttail} tail calls that lifetime of automatic
+If the compiler cannot generate a @code{musttail} tail call it reports
+an error. On some targets, tail calls may not be supported at all.
+The @code{musttail} attribute asserts that the lifetime of automatic
variables, function parameters and temporaries (unless they have non-trivial
-destruction) can end before the actual call instruction and that any access
+destruction) can end before the actual call instruction, and that any access
to those from inside of the called function results is considered undefined
behavior. Enabling @option{-O1} or @option{-O2} can improve the success of
tail calls.
@@ -9344,9 +9344,9 @@ baz (int *x)
if (*x == 1)
@{
int a = 42;
- /* The call will be tail called (would not be without the
- attribute), dereferencing the pointer in the callee is
- undefined behavior and there will be a warning emitted
+ /* The call is a tail call (would not be without the
+ attribute). Dereferencing the pointer in the callee is
+ undefined behavior, and there is a warning emitted
for this by default (@option{-Wmusttail-local-addr}). */
[[gnu::musttail]] return foo (&a);
@}
@@ -9354,9 +9354,9 @@ baz (int *x)
@{
int a = 42;
bar (&a);
- /* The call will be tail called (would not be without the
- attribute), if bar stores the pointer anywhere, dereferencing
- it in foo will be undefined behavior and there will be a warning
+ /* The call is a tail call (would not be without the
+ attribute). If bar stores the pointer anywhere, dereferencing
+ it in foo is undefined behavior. There is a warning
emitted for this with @option{-Wextra}, which implies
@option{-Wmaybe-musttail-local-addr}. */
[[gnu::musttail]] return foo (nullptr);
@@ -9365,8 +9365,8 @@ baz (int *x)
@{
S s;
/* The s variable requires non-trivial destruction which ought
- to be performed after the foo call returns, so this will
- be rejected. */
+ to be performed after the foo call returns, so this is
+ rejected. */
[[gnu::musttail]] return foo (&s.s);
@}
@}
@@ -9374,9 +9374,9 @@ baz (int *x)
To avoid the @option{-Wmaybe-musttail-local-addr} warning in the
above @code{*x == 2} case and similar code, consider defining the
-maybe escaped variables in a separate scope which will end before the
-return statement if possible to make it clear that the variable is not
-live during the call. So
+maybe-escaped variables in a separate scope that ends before the
+return statement, if that is possible, to make it clear that the
+variable is not live during the call. So:
@smallexample
else if (*x == 2)
@@ -9385,17 +9385,17 @@ live during the call. So
int a = 42;
bar (&a);
@}
- /* The call will be tail called (would not be without the
- attribute), if bar stores the pointer anywhere, dereferencing
- it in foo will be undefined behavior and there will be a warning
- emitted for this with @option{-Wextra}, which implies
- @option{-Wmaybe-musttail-local-addr}. */
+ /* The call is a tail call (would not be without the
+ attribute). If bar stores the pointer anywhere, dereferencing
+ it in foo is undefined behavior even without tail call
+ optimization, and there is no warning. */
[[gnu::musttail]] return foo (nullptr);
@}
@end smallexample
-in this case. That is not possible if it is function argument which
-is address taken because those are in scope for the whole function.
+It is not possible to avoid the warning in this way if the maybe-escaped
+variable is a function argument, because those are in scope
+for the whole function.
@end table
@node Attribute Syntax
