[PATCH] [doc] middle-end/112296 - __builtin_constant_p and side-effects

[PATCH] [doc] middle-end/112296 - __builtin_constant_p and side-effects

[Richard Biener]

The following tries to clarify the __builtin_constant_p documentation,
stating that the argument expression is not evaluated and side-effects
are discarded.  I'm struggling to find the correct terms matching
what the C language standard would call things so I'd appreciate
some help here.

OK for trunk?

Shall we diagnose arguments with side-effects?  It seems to me
such use is usually unintended?  I think rather than dropping
side-effects as a side-effect of folding the frontend should
discard them at parsing time instead, no?

Thanks,
Richard.

	PR middle-end/112296
	* doc/extend.texi (__builtin_constant_p): Clarify that
	side-effects are discarded.
---
 gcc/doc/extend.texi | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index fa7402813e7..c8fc4e391b5 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -14296,14 +14296,16 @@ an error if there is no such function.
 
 @defbuiltin{int __builtin_constant_p (@var{exp})}
 You can use the built-in function @code{__builtin_constant_p} to
-determine if a value is known to be constant at compile time and hence
-that GCC can perform constant-folding on expressions involving that
-value.  The argument of the function is the value to test.  The function
+determine if the expression @var{exp} is known to be constant at
+compile time and hence that GCC can perform constant-folding on expressions
+involving that value.  The argument of the function is the expression to test.
+The expression is not evaluated, side-effects are discarded.  The function
 returns the integer 1 if the argument is known to be a compile-time
-constant and 0 if it is not known to be a compile-time constant.  A
-return of 0 does not indicate that the value is @emph{not} a constant,
-but merely that GCC cannot prove it is a constant with the specified
-value of the @option{-O} option.
+constant and 0 if it is not known to be a compile-time constant.
+Any expression that has side-effects makes the function return 0.
+A return of 0 does not indicate that the expression is @emph{not} a constant,
+but merely that GCC cannot prove it is a constant within the constraints
+of the active set of optimization options.
 
 You typically use this function in an embedded application where
 memory is a critical resource.  If you have some complex calculation,
-- 
2.35.3

Re: [PATCH] [doc] middle-end/112296 - __builtin_constant_p and side-effects

[Joseph Myers]

On Fri, 3 Nov 2023, Richard Biener wrote:

> The following tries to clarify the __builtin_constant_p documentation,
> stating that the argument expression is not evaluated and side-effects
> are discarded.  I'm struggling to find the correct terms matching
> what the C language standard would call things so I'd appreciate
> some help here.
> 
> OK for trunk?

OK.

> Shall we diagnose arguments with side-effects?  It seems to me
> such use is usually unintended?  I think rather than dropping

The traditional use is definitely in macros to choose between code for 
constant arguments (evaluating them more than once) and maybe-out-of-line 
code for non-constant arguments (evaluating them exactly once), in which 
case having a side effect is definitely OK.

> side-effects as a side-effect of folding the frontend should
> discard them at parsing time instead, no?

I suppose the original expression needs to remain around in some form 
until the latest point at which optimizers might decide to evaluate 
__builtin_constant_p to true.  Although cases with possible side effects 
might well be optimized to false earlier; the interesting cases for 
deciding later are e.g. __builtin_constant_p called on an argument to an 
inline function (no side effects for __builtin_constant_p to discard, 
whether or not there are side effects in the caller from evaluating the 
expression passed to the function).

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [PATCH] [doc] middle-end/112296 - __builtin_constant_p and side-effects

[Richard Biener]

On Fri, 3 Nov 2023, Joseph Myers wrote:

> On Fri, 3 Nov 2023, Richard Biener wrote:
> 
> > The following tries to clarify the __builtin_constant_p documentation,
> > stating that the argument expression is not evaluated and side-effects
> > are discarded.  I'm struggling to find the correct terms matching
> > what the C language standard would call things so I'd appreciate
> > some help here.
> > 
> > OK for trunk?
> 
> OK.

Pushed.

> > Shall we diagnose arguments with side-effects?  It seems to me
> > such use is usually unintended?  I think rather than dropping
> 
> The traditional use is definitely in macros to choose between code for 
> constant arguments (evaluating them more than once) and maybe-out-of-line 
> code for non-constant arguments (evaluating them exactly once), in which 
> case having a side effect is definitely OK.

I was wondering about literally writing

 if (__builtin_constant_p (++x))
   {
    ...
   }
 else
   {
     ...
   }

which would have the surprising effects that a) it always evaluates
to false, b) the side-effect to 'x' is discarded.

> > side-effects as a side-effect of folding the frontend should
> > discard them at parsing time instead, no?
> 
> I suppose the original expression needs to remain around in some form 
> until the latest point at which optimizers might decide to evaluate 
> __builtin_constant_p to true.  Although cases with possible side effects 
> might well be optimized to false earlier; the interesting cases for 
> deciding later are e.g. __builtin_constant_p called on an argument to an 
> inline function (no side effects for __builtin_constant_p to discard, 
> whether or not there are side effects in the caller from evaluating the 
> expression passed to the function).

Yes, maybe we can improve here but as of now arguments with
side-effects will always result in a 'false' assessment as to
__builtin_constant_p, so the behavior is hardly useful apart from
having "correct" behavior for the traditional macro case.

Richard.