From patchwork Wed Feb 13 23:33:15 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Martin Sebor X-Patchwork-Id: 1041705 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=gcc.gnu.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=gcc-patches-return-496057-incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.b="tfuwGORO"; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="k50GKPBO"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 440G6z2c8Qz9rxp for ; Thu, 14 Feb 2019 10:33:29 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; q=dns; s=default; b=jJqKKwCsDQEBFxEjpY4aJ8BtGbJT62kcg+loR1jNYrTtkXXDWp 85GgMVkMAYmll94oNaAlzoqCSJp60MI4XhO3gRZxrKB/6c9ZboG4dmzym5IOHVof UpukxWvQJomaDLKfhbVB9iTcoc7Mr6Q8xBtOP0eS+JTTio7mLVARUTq24= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; s= default; bh=fcXzlVjiIy6k/Mm5SPBdEZWSVbM=; b=tfuwGOROvKbwklg2mCGo 3Heen1Bcwbu2w/1sTgLTaSng2hgjI9/++OCE8Y67qt+FhOR2eXSNY3tpQhYJlQ1I UFyUuAhbDmySMgAXUEoSRrsVeQiFYZRpPj4cQsWtYDtjPX4fom4ymOlZGhNpuluk qAUKeCb3AlO0YlXmRgExFEw= Received: (qmail 110953 invoked by alias); 13 Feb 2019 23:33:22 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 110945 invoked by uid 89); 13 Feb 2019 23:33:21 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-16.9 required=5.0 tests=BAYES_00, FREEMAIL_FROM, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE, SPF_PASS autolearn=ham version=3.3.2 spammy=odds, built-ins X-HELO: mail-qt1-f169.google.com Received: from mail-qt1-f169.google.com (HELO mail-qt1-f169.google.com) (209.85.160.169) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 13 Feb 2019 23:33:20 +0000 Received: by mail-qt1-f169.google.com with SMTP id y20so4751520qtm.13 for ; Wed, 13 Feb 2019 15:33:19 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=to:from:subject:message-id:date:user-agent:mime-version :content-language; bh=qTkyGjChbNhiqs/c4/djJedH3X2xl89ew6yb2z8oMDg=; b=k50GKPBOaFIFB5reEzY0W2Az36VRlcNWr3zrdQh5i/nEJOspjBcInTZCCXZ9lSPlW/ GY/14ZgMigZt/pqn+VZdKzbt/cDG/1/bU1MCeSbu4Eb3UjZ3RbHwiMdcrF2kGodWIWmM lJ6SCQOEXCVNLinn2dfjznaXUdX+JxPZeyNPUdnjvvjLHirv3Xetnf0oN4NZ5CBb7tFO qIfZvIgnHOJy49NxwZv+5tZaEuD/50V9NSJMCNVJrPgOVrQ/HkIrGwqbJYdmsn50HE9s BUoeLMDs8uaFZvekhvsKyaIxolIDi4FMUmY4KYv3KPwiGvZ9NHqutaR7QZ0/lM7NRhWS MplQ== Received: from [192.168.0.106] (174-16-97-54.hlrn.qwest.net. [174.16.97.54]) by smtp.gmail.com with ESMTPSA id l53sm631497qtc.33.2019.02.13.15.33.16 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 13 Feb 2019 15:33:16 -0800 (PST) To: "gcc-patches@gcc.gnu.org" From: Martin Sebor Subject: [PATCH] document __builtin_is_constant_evaluated Message-ID: <30bd73e3-9734-a1fe-ecf7-62376c21de72@gmail.com> Date: Wed, 13 Feb 2019 16:33:15 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.3.1 MIME-Version: 1.0 X-IsSubscribed: yes 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