]> Savannah Git Hosting - gnulib.git/commitdiff
verify: document ‘assume’ better
authorPaul Eggert <eggert@cs.ucla.edu>
Sat, 23 May 2020 16:41:54 +0000 (09:41 -0700)
committerPaul Eggert <eggert@cs.ucla.edu>
Sat, 23 May 2020 16:42:35 +0000 (09:42 -0700)
* lib/verify.h (assume): Say it’s for static analysis, not dynamic.

ChangeLog
lib/verify.h

index a4473284c3da4e6751e60c5de89de2adb6d75e5d..44450a3549b0b63386aa896ea903cbba16a172af 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2020-05-23  Paul Eggert  <eggert@cs.ucla.edu>
+
+       verify: document ‘assume’ better
+       * lib/verify.h (assume): Say it’s for static analysis, not dynamic.
+
 2020-05-22  Asher Gordon  <AsDaGo@posteo.net>
 
        gendocs: Clarify licenses for templates.
index d9ab89a570c903851de94de01f4269805f153f70..f1097612704aa5d0a43b966984943c5a3d1c309e 100644 (file)
@@ -277,10 +277,22 @@ template <int w>
 #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 ())