[PATCH] c/67925 - update documentation on `inline'

[PATCH] c/67925 - update documentation on `inline'

[Arkadiusz Drabczyk]

* gcc/doc/extend.texi: documentation says that functions declared
`inline' would not be integrated if they are called before they are
defined or if they are recursive. Both of these statements is now
false as shown in examples on Bugzilla.
---
 gcc/doc/extend.texi | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 79440d3..7ea4b62 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -7088,12 +7088,9 @@ function are integrated into the caller, and the function's address is
 never used, then the function's own assembler code is never referenced.
 In this case, GCC does not actually output assembler code for the
 function, unless you specify the option @option{-fkeep-inline-functions}.
-Some calls cannot be integrated for various reasons (in particular,
-calls that precede the function's definition cannot be integrated, and
-neither can recursive calls within the definition).  If there is a
-nonintegrated call, then the function is compiled to assembler code as
-usual.  The function must also be compiled as usual if the program
-refers to its address, because that can't be inlined.
+If there is a nonintegrated call, then the function is compiled to
+assembler code as usual.  The function must also be compiled as usual if
+the program refers to its address, because that can't be inlined.
 
 @opindex Winline
 Note that certain usages in a function definition can make it unsuitable
-- 
2.3.5


-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: [PATCH] c/67925 - update documentation on `inline'

[Martin Sebor]

On 10/13/2015 04:47 PM, Arkadiusz Drabczyk wrote:
> * gcc/doc/extend.texi: documentation says that functions declared
> `inline' would not be integrated if they are called before they are
> defined or if they are recursive. Both of these statements is now
> false as shown in examples on Bugzilla.

It might also be worth updating the note in the subsequent
paragraph and removing the mention of variable-length data types
which no longer prevent inlining.

FWIW, the list of most -Winline warnings issued by GCC is here
(there are two more in Ada which, AFAICT, have to do with nested
functions):

$ grep -A1 "can never be inlined" gcc/tree-inline.c
	    = G_("function %q+F can never be inlined because it uses "
		 "alloca (override using the always_inline attribute)");
--
	    = G_("function %q+F can never be inlined because it uses setjmp");
	  *handled_ops_p = true;
--
	      = G_("function %q+F can never be inlined because it "
		   "uses variable argument lists");
--
	      = G_("function %q+F can never be inlined because "
		   "it uses setjmp-longjmp exception handling");
--
	      = G_("function %q+F can never be inlined because "
		   "it uses non-local goto");
--
	      = G_("function %q+F can never be inlined because "
		   "it uses __builtin_return or __builtin_apply_args");
--
	    = G_("function %q+F can never be inlined "
		 "because it contains a computed goto");
--
         warning (OPT_Winline, "function %q+F can never be inlined 
because it "
                  "is suppressed using -fno-inline", fn);
--
         warning (OPT_Winline, "function %q+F can never be inlined 
because it "
                  "uses attributes conflicting with inlining", fn);

Martin

> ---
>   gcc/doc/extend.texi | 9 +++------
>   1 file changed, 3 insertions(+), 6 deletions(-)
>
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index 79440d3..7ea4b62 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -7088,12 +7088,9 @@ function are integrated into the caller, and the function's address is
>   never used, then the function's own assembler code is never referenced.
>   In this case, GCC does not actually output assembler code for the
>   function, unless you specify the option @option{-fkeep-inline-functions}.
> -Some calls cannot be integrated for various reasons (in particular,
> -calls that precede the function's definition cannot be integrated, and
> -neither can recursive calls within the definition).  If there is a
> -nonintegrated call, then the function is compiled to assembler code as
> -usual.  The function must also be compiled as usual if the program
> -refers to its address, because that can't be inlined.
> +If there is a nonintegrated call, then the function is compiled to
> +assembler code as usual.  The function must also be compiled as usual if
> +the program refers to its address, because that can't be inlined.
>
>   @opindex Winline
>   Note that certain usages in a function definition can make it unsuitable
>

Re: [PATCH] c/67925 - update documentation on `inline'

[Arkadiusz Drabczyk]

On Wed, Oct 14, 2015 at 08:36:43AM -0600, Martin Sebor wrote:
> On 10/13/2015 04:47 PM, Arkadiusz Drabczyk wrote:
> >* gcc/doc/extend.texi: documentation says that functions declared
> >`inline' would not be integrated if they are called before they are
> >defined or if they are recursive. Both of these statements is now
> >false as shown in examples on Bugzilla.
> 
> It might also be worth updating the note in the subsequent
> paragraph and removing the mention of variable-length data types
> which no longer prevent inlining.

Done.  I also removed the mention of nested functions as the following
code compiled with GCC 6.0 doesn't give any warning with -O2 -Winline
and main() is the only function defined in assembler code:

#include <stdio.h>
#include <stdlib.h>

inline static int foo (int a, int b)
{
	printf("a == %d\n", a);
	inline int square (int z) { return z * z; }

	return square (a) + square (b);
}

int main(int argc, char *argv[])
{
	printf("%d\n", foo(atoi(argv[1]), atoi(argv[2])));
	exit(0);
}

I also removed a reference to Bugzilla from the commit message, I
don't think it's necessary.

> FWIW, the list of most -Winline warnings issued by GCC is here
> (there are two more in Ada which, AFAICT, have to do with nested
> functions):
> 
> $ grep -A1 "can never be inlined" gcc/tree-inline.c
> (...)
> --
> 	      = G_("function %q+F can never be inlined because "
> 		   "it uses non-local goto");

I tested of all of these and listed them in the documentation but
wasn't able to reproduce this one.  The following code does not give
any warning with -O2 -Winline:

#include <stdio.h>
#include <stdlib.h>
#include <setjmp.h>

static jmp_buf buf;

inline static void longjmp_test(int n)
{
	puts("hi");

	if (n == 2)
		longjmp(buf, 2);
}

int main(int argc, char *argv[])
{
	printf("%d\n", setjmp(buf));
	longjmp_test(atoi(argv[1]));
	puts("next line in a normal execution");
	exit(0);
}

Is this test case correct?  However, I get the following warning using
__builtin_longjmp() instead of longjmp():

warning: function 'longjmp_test' can never be inlined because it uses
setjmp-longjmp exception handling [-Winline]
>8------------------------------------------------------8<
* gcc/doc/extend.texi: documentation says that functions declared
`inline' would not be integrated if they are called before they are
defined, if they are recursive, if they use variable-length data types
or if they are nested.  All of these statements are now false and have
been removed. Mention of setjmp(), __builtin_return() and
__builtin_apply_args() has been added.
---
 gcc/doc/extend.texi | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 79440d3..be95cc3 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -7088,21 +7088,18 @@ function are integrated into the caller, and the function's address is
 never used, then the function's own assembler code is never referenced.
 In this case, GCC does not actually output assembler code for the
 function, unless you specify the option @option{-fkeep-inline-functions}.
-Some calls cannot be integrated for various reasons (in particular,
-calls that precede the function's definition cannot be integrated, and
-neither can recursive calls within the definition).  If there is a
-nonintegrated call, then the function is compiled to assembler code as
-usual.  The function must also be compiled as usual if the program
-refers to its address, because that can't be inlined.
+If there is a nonintegrated call, then the function is compiled to
+assembler code as usual.  The function must also be compiled as usual if
+the program refers to its address, because that can't be inlined.
 
 @opindex Winline
 Note that certain usages in a function definition can make it unsuitable
-for inline substitution.  Among these usages are: variadic functions, use of
-@code{alloca}, use of variable-length data types (@pxref{Variable Length}),
-use of computed goto (@pxref{Labels as Values}), use of nonlocal goto,
-and nested functions (@pxref{Nested Functions}).  Using @option{-Winline}
-warns when a function marked @code{inline} could not be substituted,
-and gives the reason for the failure.
+for inline substitution.  Among these usages are: variadic functions,
+use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
+use of @code{setjmp} and use of @code{__builtin_return} or
+@code{__builtin_apply_args}.  Using @option{-Winline} warns when a
+function marked @code{inline} could not be substituted, and gives the
+reason for the failure.
 
 @cindex automatic @code{inline} for C++ member fns
 @cindex @code{inline} automatic for C++ member fns
-- 
2.3.5


-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: [PATCH] c/67925 - update documentation on `inline'

[Martin Sebor]

On 10/14/2015 03:42 PM, Arkadiusz Drabczyk wrote:
> On Wed, Oct 14, 2015 at 08:36:43AM -0600, Martin Sebor wrote:
>> On 10/13/2015 04:47 PM, Arkadiusz Drabczyk wrote:
>>> * gcc/doc/extend.texi: documentation says that functions declared
>>> `inline' would not be integrated if they are called before they are
>>> defined or if they are recursive. Both of these statements is now
>>> false as shown in examples on Bugzilla.
>>
>> It might also be worth updating the note in the subsequent
>> paragraph and removing the mention of variable-length data types
>> which no longer prevent inlining.
>
> Done.  I also removed the mention of nested functions as the following
> code compiled with GCC 6.0 doesn't give any warning with -O2 -Winline
> and main() is the only function defined in assembler code:

I think this is the Ada-specific warning I mentioned (see
check_inlining_for_nested_subprog in gcc/ada/gcc-interface/trans.c)
so the part about nested functions needs to stay.

>> 	      = G_("function %q+F can never be inlined because "
>> 		   "it uses non-local goto");
>
> I tested of all of these and listed them in the documentation but
> wasn't able to reproduce this one.  The following code does not give
> any warning with -O2 -Winline:

The warning above is issued for non-local and computed goto. You can
find examples of both in the test suite (find gcc/testsuite/ -name
"*goto*.[cC]")

>
> #include <stdio.h>
> #include <stdlib.h>
> #include <setjmp.h>
>
> static jmp_buf buf;
>
> inline static void longjmp_test(int n)
> {
> 	puts("hi");
>
> 	if (n == 2)
> 		longjmp(buf, 2);
> }
>
> int main(int argc, char *argv[])
> {
> 	printf("%d\n", setjmp(buf));
> 	longjmp_test(atoi(argv[1]));
> 	puts("next line in a normal execution");
> 	exit(0);
> }
>
> Is this test case correct?

Not really. You can see the warning by calling setjmp in longjmp_test.

>  However, I get the following warning using
> __builtin_longjmp() instead of longjmp():
>
> warning: function 'longjmp_test' can never be inlined because it uses
> setjmp-longjmp exception handling [-Winline]

Right. You can see why in the comment in gcc/tree-inline.c:
             /* We can't inline functions that call __builtin_longjmp at
                all.  The non-local goto machinery really requires the
                destination be in a different function.  If we allow the
                function calling __builtin_longjmp to be inlined into the
                function calling __builtin_setjmp, Things will Go Awry.  */
             inline_forbidden_reason
               = G_("function %q+F can never be inlined because "
                    "it uses setjmp-longjmp exception handling");

>> 8------------------------------------------------------8<
> * gcc/doc/extend.texi: documentation says that functions declared
> `inline' would not be integrated if they are called before they are
> defined, if they are recursive, if they use variable-length data types
> or if they are nested.  All of these statements are now false and have
> been removed. Mention of setjmp(), __builtin_return() and
> __builtin_apply_args() has been added.

Great, thank you for taking the time to make these additional updates.
Modulo the nested functions, the patch looks good to me (someone else
will need to formally approve the final version).

Martin

> ---
>   gcc/doc/extend.texi | 21 +++++++++------------
>   1 file changed, 9 insertions(+), 12 deletions(-)
>
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index 79440d3..be95cc3 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -7088,21 +7088,18 @@ function are integrated into the caller, and the function's address is
>   never used, then the function's own assembler code is never referenced.
>   In this case, GCC does not actually output assembler code for the
>   function, unless you specify the option @option{-fkeep-inline-functions}.
> -Some calls cannot be integrated for various reasons (in particular,
> -calls that precede the function's definition cannot be integrated, and
> -neither can recursive calls within the definition).  If there is a
> -nonintegrated call, then the function is compiled to assembler code as
> -usual.  The function must also be compiled as usual if the program
> -refers to its address, because that can't be inlined.
> +If there is a nonintegrated call, then the function is compiled to
> +assembler code as usual.  The function must also be compiled as usual if
> +the program refers to its address, because that can't be inlined.
>
>   @opindex Winline
>   Note that certain usages in a function definition can make it unsuitable
> -for inline substitution.  Among these usages are: variadic functions, use of
> -@code{alloca}, use of variable-length data types (@pxref{Variable Length}),
> -use of computed goto (@pxref{Labels as Values}), use of nonlocal goto,
> -and nested functions (@pxref{Nested Functions}).  Using @option{-Winline}
> -warns when a function marked @code{inline} could not be substituted,
> -and gives the reason for the failure.
> +for inline substitution.  Among these usages are: variadic functions,
> +use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
> +use of @code{setjmp} and use of @code{__builtin_return} or
> +@code{__builtin_apply_args}.  Using @option{-Winline} warns when a
> +function marked @code{inline} could not be substituted, and gives the
> +reason for the failure.
>
>   @cindex automatic @code{inline} for C++ member fns
>   @cindex @code{inline} automatic for C++ member fns
>

Re: [PATCH] c/67925 - update documentation on `inline'

[Arkadiusz Drabczyk]

On Wed, Oct 14, 2015 at 06:18:03PM -0600, Martin Sebor wrote:
> On 10/14/2015 03:42 PM, Arkadiusz Drabczyk wrote:
> >On Wed, Oct 14, 2015 at 08:36:43AM -0600, Martin Sebor wrote:
> >>On 10/13/2015 04:47 PM, Arkadiusz Drabczyk wrote:
> >>>* gcc/doc/extend.texi: documentation says that functions declared
> >>>`inline' would not be integrated if they are called before they are
> >>>defined or if they are recursive. Both of these statements is now
> >>>false as shown in examples on Bugzilla.
> >>
> >>It might also be worth updating the note in the subsequent
> >>paragraph and removing the mention of variable-length data types
> >>which no longer prevent inlining.
> >
> >Done.  I also removed the mention of nested functions as the following
> >code compiled with GCC 6.0 doesn't give any warning with -O2 -Winline
> >and main() is the only function defined in assembler code:
> 
> I think this is the Ada-specific warning I mentioned (see
> check_inlining_for_nested_subprog in gcc/ada/gcc-interface/trans.c)
> so the part about nested functions needs to stay.

Ok, I brought it back.

> >>	      = G_("function %q+F can never be inlined because "
> >>		   "it uses non-local goto");
> >
> >I tested of all of these and listed them in the documentation but
> >wasn't able to reproduce this one.  The following code does not give
> >any warning with -O2 -Winline:
> 
> The warning above is issued for non-local and computed goto. You can
> find examples of both in the test suite (find gcc/testsuite/ -name
> "*goto*.[cC]")

Aha, ok, I just thought that longjmp() counts as a non-local goto
here.  Indeed, this code invokes `function 'bar' can never be inlined
because it uses non-local goto' with -O2 -Winline (but only if
function that contains goto is nested, otherwise it fails to compile):

#include <stdio.h>
#include <stdlib.h>

int main (void)
{
	__label__ l1;

	void foo (void)
	{

		inline void bar (void)
		{
			puts ("goto l1");
			goto l1;
		}

		bar ();
	}

	foo ();
	abort ();
 l1:
	puts ("label l1");
	return 0;
}

I brought back a mention of nonlocal goto and added a mention of
__builtin_longjmp() as the usual longjmp() does not prevent inlining.

>8------------------------------------------------------8<
* gcc/doc/extend.texi: documentation says that functions declared
`inline' would not be integrated if they are called before they are
defined, if they are recursive, if they use variable-length data types
or if they are nested.  All of these statements are now false and have
been removed. Mention of setjmp(), __builtin_longjmp(),
__builtin_return() and __builtin_apply_args() has been added.
---
 gcc/doc/extend.texi | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 79440d3..bd559af 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -7088,21 +7088,19 @@ function are integrated into the caller, and the function's address is
 never used, then the function's own assembler code is never referenced.
 In this case, GCC does not actually output assembler code for the
 function, unless you specify the option @option{-fkeep-inline-functions}.
-Some calls cannot be integrated for various reasons (in particular,
-calls that precede the function's definition cannot be integrated, and
-neither can recursive calls within the definition).  If there is a
-nonintegrated call, then the function is compiled to assembler code as
-usual.  The function must also be compiled as usual if the program
-refers to its address, because that can't be inlined.
+If there is a nonintegrated call, then the function is compiled to
+assembler code as usual.  The function must also be compiled as usual if
+the program refers to its address, because that can't be inlined.
 
 @opindex Winline
 Note that certain usages in a function definition can make it unsuitable
-for inline substitution.  Among these usages are: variadic functions, use of
-@code{alloca}, use of variable-length data types (@pxref{Variable Length}),
-use of computed goto (@pxref{Labels as Values}), use of nonlocal goto,
-and nested functions (@pxref{Nested Functions}).  Using @option{-Winline}
-warns when a function marked @code{inline} could not be substituted,
-and gives the reason for the failure.
+for inline substitution.  Among these usages are: variadic functions,
+use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
+use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
+of @code{__builtin_longjmp} and use of @code{__builtin_return} or
+@code{__builtin_apply_args}.  Using @option{-Winline} warns when a
+function marked @code{inline} could not be substituted, and gives the
+reason for the failure.
 
 @cindex automatic @code{inline} for C++ member fns
 @cindex @code{inline} automatic for C++ member fns
-- 
2.3.5


-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: [PATCH] c/67925 - update documentation on `inline'

[Jeff Law]

On 10/15/2015 06:25 AM, Arkadiusz Drabczyk wrote:
> On Wed, Oct 14, 2015 at 06:18:03PM -0600, Martin Sebor wrote:
>> >On 10/14/2015 03:42 PM, Arkadiusz Drabczyk wrote:
>>> > >On Wed, Oct 14, 2015 at 08:36:43AM -0600, Martin Sebor wrote:
>>>> > >>On 10/13/2015 04:47 PM, Arkadiusz Drabczyk wrote:
>>>>> > >>>* gcc/doc/extend.texi: documentation says that functions declared
>>>>> > >>>`inline' would not be integrated if they are called before they are
>>>>> > >>>defined or if they are recursive. Both of these statements is now
>>>>> > >>>false as shown in examples on Bugzilla.
>>>> > >>
>>>> > >>It might also be worth updating the note in the subsequent
>>>> > >>paragraph and removing the mention of variable-length data types
>>>> > >>which no longer prevent inlining.
>>> > >
>>> > >Done.  I also removed the mention of nested functions as the following
>>> > >code compiled with GCC 6.0 doesn't give any warning with -O2 -Winline
>>> > >and main() is the only function defined in assembler code:
>> >
>> >I think this is the Ada-specific warning I mentioned (see
>> >check_inlining_for_nested_subprog in gcc/ada/gcc-interface/trans.c)
>> >so the part about nested functions needs to stay.
> Ok, I brought it back.
>
>>>> > >>	      = G_("function %q+F can never be inlined because "
>>>> > >>		   "it uses non-local goto");
>>> > >
>>> > >I tested of all of these and listed them in the documentation but
>>> > >wasn't able to reproduce this one.  The following code does not give
>>> > >any warning with -O2 -Winline:
>> >
>> >The warning above is issued for non-local and computed goto. You can
>> >find examples of both in the test suite (find gcc/testsuite/ -name
>> >"*goto*.[cC]")
> Aha, ok, I just thought that longjmp() counts as a non-local goto
> here.  Indeed, this code invokes `function 'bar' can never be inlined
> because it uses non-local goto' with -O2 -Winline (but only if
> function that contains goto is nested, otherwise it fails to compile):
>
> #include <stdio.h>
> #include <stdlib.h>
>
> int main (void)
> {
> 	__label__ l1;
>
> 	void foo (void)
> 	{
>
> 		inline void bar (void)
> 		{
> 			puts ("goto l1");
> 			goto l1;
> 		}
>
> 		bar ();
> 	}
>
> 	foo ();
> 	abort ();
>   l1:
> 	puts ("label l1");
> 	return 0;
> }
>
> I brought back a mention of nonlocal goto and added a mention of
> __builtin_longjmp() as the usual longjmp() does not prevent inlining.
Thanks Arkadiusz & Martin.  I committed this version to the trunk.

jeff