Mercurial > gnulib

comparison doc/verify.texi @ 37203:2f0a7cf7ea66

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
verify: document some 'assume' pitfalls * doc/verify.texi (Compile-time Assertions): Mention that 'assume (E)' can sometimes slow things down. Use CHAR_MAX + 1, not UCHAR_MAX + 1.
author Paul Eggert <eggert@cs.ucla.edu>
date Thu, 10 Oct 2013 21:30:16 -0700
parents 2f1343191e67
children 344018b6e5d7
comparison
equal deleted inserted replaced
37202:143cea48b4d3 37203:2f0a7cf7ea66
61 within a @code{struct} or @code{union} specifier, in place of an 61 within a @code{struct} or @code{union} specifier, in place of an
62 ordinary member declaration. Second, they require the programmer to 62 ordinary member declaration. Second, they require the programmer to
63 specify a compile-time diagnostic as a string literal. 63 specify a compile-time diagnostic as a string literal.
64 64
65 The @file{verify.h} header defines one more macro, @code{assume 65 The @file{verify.h} header defines one more macro, @code{assume
66 (@var{E})}. This macro expands to an expression of type @code{void} 66 (@var{E})}, which expands to an expression of type @code{void}
67 that causes the compiler to assume that the expression @var{E} yields 67 that causes the compiler to assume that @var{E} yields a nonzero
68 a nonzero value. @var{E} should be of a scalar type, and should not 68 value. @var{E} should be a scalar expression, and should not
69 have side effects; it may or may not be evaluated. The behavior is 69 have side effects; it may or may not be evaluated. The behavior is
70 undefined if @var{E} would yield zero. The main use of @code{assume} 70 undefined if @var{E} would yield zero. The main use of @code{assume}
71 is optimization, as the compiler may be able to generate better code 71 is optimization, as the compiler may be able to generate better code
72 if it knows that @var{E} is true. 72 if it assumes @var{E}. For best results, @var{E} should be simple
73 enough that a compiler can determine that it has no side effects: if
74 @var{E} calls an external function or accesses volatile storage the
75 compiler may not be able to optimize @var{E} away and @code{assume
76 (@var{E})} may therefore slow down the program.
73 77
74 Here are some example uses of @code{verify} and @code{verify_expr}. 78 Here are some example uses of these macros.
75 79
76 @example 80 @example
77 #include <verify.h> 81 #include <verify.h>
78 82
79 #include <limits.h> 83 #include <limits.h>
97 so that the result is of type T 101 so that the result is of type T
98 even when T is narrower than unsigned int. */ 102 even when T is narrower than unsigned int. */
99 #define MAX_UNSIGNED_VAL(t) \ 103 #define MAX_UNSIGNED_VAL(t) \
100 ((T) verify_expr (0 < (T) -1, -1)) 104 ((T) verify_expr (0 < (T) -1, -1))
101 105
102 /* Return T divided by UCHAR_MAX + 1. Behavior is undefined 106 /* Return T divided by CHAR_MAX + 1, where behavior is
103 if T is negative, and in the typical case where UCHAR_MAX 107 undefined if T < 0. In the common case where CHAR_MAX
104 is 255 the compiler can therefore implement the division 108 is 127 the compiler can therefore implement the division
105 by shifting T right 8 bits, an optimization that would 109 by shifting T right 7 bits, an optimization that would
106 not be valid if T were negative. */ 110 not be valid if T were negative. */
107 time_t 111 time_t
108 time_index (time_t t) 112 time_index (time_t t)
109 @{ 113 @{
110 assume (0 <= t); 114 assume (0 <= t);
111 return t / (UCHAR_MAX + 1); 115 return t / (CHAR_MAX + 1);
112 @} 116 @}
113 117
114 118
115 @end example 119 @end example