Message ID | 20240202091322.1898280-6-ak@linux.intel.com |
---|---|
State | New |
Headers | show |
Series | [v4,1/5] Improve must tail in RTL backend | expand |
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
On Sat, Feb 03, 2024 at 09:35:43PM -0700, Sandra Loosemore wrote: > 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 FWIW we always had, they just were ignored (with a warning) Thanks Sandra. I applied the changes. Diff appeneded for reference. diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 866f6c4a9fed..fe1ee245ed69 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -9818,7 +9818,7 @@ same manner as the @code{deprecated} attribute. @section Statement Attributes @cindex Statement Attributes -GCC allows attributes to be set on null statements. @xref{Attribute Syntax}, +GCC allows attributes to be set on statements. @xref{Attribute Syntax}, for details of the exact syntax for using attributes. Other attributes are available for functions (@pxref{Function Attributes}), variables (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators @@ -9879,15 +9879,15 @@ have to optimize it to just @code{return 42 + 42;}. @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. +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 +If the compiler cannot generate a tail call it generates an error. Tail calls generally require enabling optimization. On some targets they may not be supported. @@ -10014,7 +10014,9 @@ the constant expression, if present. @subsubheading Statement Attributes In GNU C, an attribute specifier list may appear as part of a null -statement. The attribute goes before the semicolon. +statement. The attribute goes before the semicolon. +Some attributes in new style syntax are also supported +on non-null statements. @subsubheading Type Attributes
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. + +@smallexample +[[gnu::musttail]] return foo(); +@end smallexample + +If the compiler cannot generate a tail call it will generate +an error. Tail calls generally require enabling optimization. +On some targets they may not be supported. + @end table @node Attribute Syntax