>From b2c8d02c9750f335549781d20fa37415c9a1edb3 Mon Sep 17 00:00:00 2001
From: Paul Eggert
Date: Sat, 23 May 2020 09:41:54 -0700
Subject: [PATCH] =?UTF-8?q?verify:=20document=20=E2=80=98assume=E2=80=99?=
=?UTF-8?q?=20better?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* lib/verify.h (assume): Say it’s for static analysis, not dynamic.
---
ChangeLog | 5 +++++
lib/verify.h | 20 ++++++++++++++++----
2 files changed, 21 insertions(+), 4 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index a4473284c..44450a354 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2020-05-23 Paul Eggert
+
+ verify: document ‘assume’ better
+ * lib/verify.h (assume): Say it’s for static analysis, not dynamic.
+
2020-05-22 Asher Gordon
gendocs: Clarify licenses for templates.
diff --git a/lib/verify.h b/lib/verify.h
index d9ab89a57..f10976127 100644
--- a/lib/verify.h
+++ b/lib/verify.h
@@ -277,10 +277,22 @@ template
#endif
/* Assume that R always holds. Behavior is undefined if R is false,
- fails to evaluate, or has side effects. Although assuming R can
- help a compiler generate better code or diagnostics, performance
- can suffer if R uses hard-to-optimize features such as function
- calls not inlined by the compiler. */
+ fails to evaluate, or has side effects.
+
+ 'assume (R)' is a directive from the programmer telling the
+ compiler that R is true so the compiler needn't generate code to
+ test R. This is why 'assume' is in verify.h: it's related to
+ static checking (in this case, static checking done by the
+ programmer), not dynamic checking.
+
+ 'assume (R)' can affect compilation of all the code, not just code
+ that happens to be executed after the assume (R) is "executed".
+ For example, if the code mistakenly does 'assert (R); assume (R);'
+ the compiler is entitled to optimize away the 'assert (R)'.
+
+ Although assuming R can help a compiler generate better code or
+ diagnostics, performance can suffer if R uses hard-to-optimize
+ features such as function calls not inlined by the compiler. */
#if _GL_HAS_BUILTIN_UNREACHABLE
# define assume(R) ((R) ? (void) 0 : __builtin_unreachable ())
--
2.17.1