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
gcc/ChangeLog:
* doc/extend.texi (Other Builtins): Add
__builtin_is_constant_evaluated.
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
+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
