document __builtin_is_constant_evaluated

The attached patch adds the __builtin_is_constant_evaluated newly
introduced in GCC 9 to the Other Builtins section in the manual.

I followed the example of __builtin_setjmp and __builtin_longjmp
by encouraging the use of std::is_constant_evaluated over making
use of the built-in directly.

There have been questions of the value of documenting built-ins
intended to be used by the implementation itself.  There are
good reasons to document all built-ins (and similar extensions)
regardless.  First, the manual is used as a reference not just
by compiler users but also by GCC contributors.  I noticed
the missing documentation while looking for background for a bug
report in pr88977 from a user calling the built-in directly.
(I wanted to check to make sure the built-ins wasn't documented
as experimental or otherwise lacking in expected functionality.)
Documenting a feature as not intended for direct use is better
than not documenting it at all: it makes the intent clear.
Leaving it undocumented and hoping that users won't find it
obviously doesn't work.  Plenty of users read libdstdc++ code,
either while debugging their own programs, or simply out of
curiosity, and so are unavoidably exposed to extensions like
this.  Besides libstdc++ there are also other standard library
implementations that use GCC and that may want to make use of
the built-in.  There are also GCC-compatible compilers that need
to compile libstdc++ code and whose writers need to know about
GCC built-ins.  Many of these writers cannot for IP reasons study
GCC sources (and some may be uncomfortable looking at GCC tests)
and the only information they have access to is the GCC manual.
The absence of documentation makes everyone's work more difficult
and increases the odds that it will be used incorrectly by any of
these users.

Martin

On 2/13/19 4:33 PM, Martin Sebor wrote:

> Index: gcc/doc/extend.texi
> ===================================================================
> --- gcc/doc/extend.texi	(revision 268856)
> +++ gcc/doc/extend.texi	(working copy)
> @@ -12890,6 +12890,22 @@ built-in in this case, because it has no opportuni
>  optimization.
>  @end deftypefn
>  
> +@deftypefn {Built-in Function} bool __builtin_is_constant_evaluated ()
> +The @code{__builtin_is_constant_evaluated} function is available only
> +in C++.  Its main use case is to determine whether a @code{constexpr}
> +function is being called in a @code{constexpr} context.  A call to
> +the function evaluates to a core constant expression with the value
> +@code{true} if and only if it occurs within the evaluation of an expression
> +or conversion that is manifestly constant-evaluated as defined in the C++
> +standard.  Manifestly constant-evaluated contexts include constant-expressions,
> +the conditions of @code{constexpr if} statements, constraint-expresions, and

s/expresions/expressions/

> +initializers of variables usable in constant expressions.  The built-in is
> +intended to be used by implementations of the @code{std::is_constant_evaluated}
> +C++ function.  Programs should make use of the latter function rather than
> +invoking the built-in directly.  For more details refer to the latest revision
> +of the C++ standard.
> +@end deftypefn
> +
>  @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
>  @opindex fprofile-arcs
>  You may use @code{__builtin_expect} to provide the compiler with

I think this is generally reasonable (and I agree with the rationale for 
documenting this at all), but I'd like to see this rearranged and 
rephrased to put the most important point (it's an internal hook to 
implement std::is_constant_evaluated and shouldn't be called directly) 
before the technical details, with a paragraph break in between.

-Sandra

On 2/15/19 9:01 PM, Sandra Loosemore wrote:
> On 2/13/19 4:33 PM, Martin Sebor wrote:
> 
>> Index: gcc/doc/extend.texi
>> ===================================================================
>> --- gcc/doc/extend.texi    (revision 268856)
>> +++ gcc/doc/extend.texi    (working copy)
>> @@ -12890,6 +12890,22 @@ built-in in this case, because it has no 
>> opportuni
>>  optimization.
>>  @end deftypefn
>>
>> +@deftypefn {Built-in Function} bool __builtin_is_constant_evaluated ()
>> +The @code{__builtin_is_constant_evaluated} function is available only
>> +in C++.  Its main use case is to determine whether a @code{constexpr}
>> +function is being called in a @code{constexpr} context.  A call to
>> +the function evaluates to a core constant expression with the value
>> +@code{true} if and only if it occurs within the evaluation of an 
>> expression
>> +or conversion that is manifestly constant-evaluated as defined in the 
>> C++
>> +standard.  Manifestly constant-evaluated contexts include 
>> constant-expressions,
>> +the conditions of @code{constexpr if} statements, 
>> constraint-expresions, and
> 
> s/expresions/expressions/
> 
>> +initializers of variables usable in constant expressions.  The 
>> built-in is
>> +intended to be used by implementations of the 
>> @code{std::is_constant_evaluated}
>> +C++ function.  Programs should make use of the latter function rather 
>> than
>> +invoking the built-in directly.  For more details refer to the latest 
>> revision
>> +of the C++ standard.
>> +@end deftypefn
>> +
>>  @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, 
>> long @var{c})
>>  @opindex fprofile-arcs
>>  You may use @code{__builtin_expect} to provide the compiler with
> 
> I think this is generally reasonable (and I agree with the rationale for 
> documenting this at all), but I'd like to see this rearranged and 
> rephrased to put the most important point (it's an internal hook to 
> implement std::is_constant_evaluated and shouldn't be called directly) 
> before the technical details, with a paragraph break in between.

Attached is a revision with this rearrangement.

Martin
gcc/ChangeLog:

	* doc/extend.texi (Other Builtins): Add
	__builtin_is_constant_evaluated.

Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi	(revision 268992)
+++ gcc/doc/extend.texi	(working copy)
@@ -12890,6 +12890,23 @@ built-in in this case, because it has no opportuni
 optimization.
 @end deftypefn
 
+@deftypefn {Built-in Function} bool __builtin_is_constant_evaluated ()
+The @code{__builtin_is_constant_evaluated} function is available only
+in C++.  The built-in is intended to be used by implemetations of
+the @code{std::is_constant_evaluated} C++ function.  Programs should make
+use of the latter function rather than invoking the built-in directly.
+
+The main use case of the built-in is to determine whether a @code{constexpr}
+function is being called in a @code{constexpr} context.  A call to
+the function evaluates to a core constant expression with the value
+@code{true} if and only if it occurs within the evaluation of an expression
+or conversion that is manifestly constant-evaluated as defined in the C++
+standard.  Manifestly constant-evaluated contexts include constant-expressions,
+the conditions of @code{constexpr if} statements, constraint-expressions, and
+initializers of variables usable in constant expressions.   For more details
+refer to the latest revision of the C++ standard.
+@end deftypefn
+
 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
 @opindex fprofile-arcs
 You may use @code{__builtin_expect} to provide the compiler with

On 2/18/19 11:52 AM, Martin Sebor wrote:
> Index: gcc/doc/extend.texi
> ===================================================================
> --- gcc/doc/extend.texi	(revision 268992)
> +++ gcc/doc/extend.texi	(working copy)
> @@ -12890,6 +12890,23 @@ built-in in this case, because it has no opportuni
>  optimization.
>  @end deftypefn
>  
> +@deftypefn {Built-in Function} bool __builtin_is_constant_evaluated ()
> +The @code{__builtin_is_constant_evaluated} function is available only
> +in C++.  The built-in is intended to be used by implemetations of

s/implemetations/implementations/

> +the @code{std::is_constant_evaluated} C++ function.  Programs should make
> +use of the latter function rather than invoking the built-in directly.
> +
> +The main use case of the built-in is to determine whether a @code{constexpr}
> +function is being called in a @code{constexpr} context.  A call to
> +the function evaluates to a core constant expression with the value
> +@code{true} if and only if it occurs within the evaluation of an expression
> +or conversion that is manifestly constant-evaluated as defined in the C++
> +standard.  Manifestly constant-evaluated contexts include constant-expressions,
> +the conditions of @code{constexpr if} statements, constraint-expressions, and
> +initializers of variables usable in constant expressions.   For more details
> +refer to the latest revision of the C++ standard.
> +@end deftypefn
> +
>  @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
>  @opindex fprofile-arcs
>  You may use @code{__builtin_expect} to provide the compiler with

This is OK with the typo fixed.

-Sandra