X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fverify.texi;h=bd38c077684d737ee35c155ee2f519cfd063a088;hb=ab509afde2e2572fe70ff0c55e3bf7ff289a9f40;hp=f95279d6928475cf8bba5cb79ed07f31c20d0771;hpb=aa93a59f7a386221797b809f18ee670edfbaff02;p=gnulib.git diff --git a/doc/verify.texi b/doc/verify.texi index f95279d69..bd38c0776 100644 --- a/doc/verify.texi +++ b/doc/verify.texi @@ -1,6 +1,6 @@ @c GNU verify module documentation -@c Copyright (C) 2006, 2009-2011 Free Software Foundation, Inc. +@c Copyright (C) 2006, 2009-2013 Free Software Foundation, Inc. @c Permission is granted to copy, distribute and/or modify this document @c under the terms of the GNU Free Documentation License, Version 1.3 @@ -14,48 +14,68 @@ @cindex assertion @findex verify -@findex verify_true +@findex verify_expr -The @samp{verify} module supports compile-time tests, as opposed to -the standard @code{assert} macro which supports only runtime tests. -Since the tests occur at compile-time, they are more reliable, and -they require no runtime overhead. +This module provides a header file @file{verify.h} that defines +macros related to compile-time verification. -This module provides a header file @file{verify.h} that defines two -macros: @code{verify (@var{EXPRESSION})} and @code{verify_true -(@var{EXPRESSION})}. Both accept an integer constant expression -argument and verify that it is nonzero. If not, a compile-time error +Two of these macros are @code{verify (@var{V})} and @code{verify_expr +(@var{V}, @var{EXPR})}. Both accept an integer constant expression +argument @var{V} and verify that it is nonzero. If not, a compile-time error results. -@code{verify (@var{EXPRESSION});} is a declaration; it can occur -outside of functions. In contrast, @code{verify_true -(@var{EXPRESSION})} is an integer constant expression that always -evaluates to 1; it can be used in macros that expand to -expressions. +These two macros implement compile-time tests, as opposed to +the standard @code{assert} macro which supports only runtime tests. +Since the tests occur at compile-time, they are more reliable, and +they require no runtime overhead. -@var{EXPRESSION} should be an integer constant expression in the sense +@code{verify (@var{V});} is a declaration; it can occur outside of +functions. In contrast, @code{verify_expr (@var{V}, @var{EXPR})} is +an expression that returns the value of @var{EXPR}; it can be used in +macros that expand to expressions. If @var{EXPR} is an integer +constant expression, then @code{verify_expr (@var{V}, @var{EXPR})} is +also an integer constant expression. Although @var{EXPR} and +@code{verify_expr (@var{V}, @var{EXPR})}@ are guaranteed to have the +same side effects and value and type (after integer promotion), they +need not have the same type if @var{EXPR}'s type is an integer that is +narrower than @code{int} or @code{unsigned int}. + +@var{V} should be an integer constant expression in the sense of the C standard. Its leaf operands should be integer, enumeration, or character constants; or @code{sizeof} expressions that return constants; or floating constants that are the immediate operands of -casts. Outside a @code{sizeof} subexpression, @var{EXPRESSION} should +casts. Outside a @code{sizeof} subexpression, @var{V} should not contain any assignments, function calls, comma operators, casts to non-integer types, or subexpressions whose values are outside the -representable ranges for their types. If @var{EXPRESSION} is not an +representable ranges for their types. If @var{V} is not an integer constant expression, then a compiler might reject a usage like -@samp{verify (@var{EXPRESSION});} even when @var{EXPRESSION} is +@samp{verify (@var{V});} even when @var{V} is nonzero. -Although the standard @code{assert} macro is a runtime test, draft C1X -specifies a builtin @code{_Static_assert (@var{EXPRESSION}, +Although the standard @code{assert} macro is a runtime test, C11 +specifies a builtin @code{_Static_assert (@var{V}, @var{STRING-LITERAL})}, its @file{assert.h} header has a similar macro -named @code{static_assert}, and draft C++0X has a similar -@code{static_assert} builtin. These draft builtins and macros differ +named @code{static_assert}, and C++11 has a similar +@code{static_assert} builtin. These builtins and macros differ from @code{verify} in two major ways. First, they can also be used within a @code{struct} or @code{union} specifier, in place of an ordinary member declaration. Second, they require the programmer to specify a compile-time diagnostic as a string literal. -Here are some example uses of @code{verify} and @code{verify_true}. +The @file{verify.h} header defines one more macro, @code{assume +(@var{E})}, which expands to an expression of type @code{void} +that causes the compiler to assume that @var{E} yields a nonzero +value. @var{E} should be a scalar expression, and should not +have side effects; it may or may not be evaluated. The behavior is +undefined if @var{E} would yield zero. The main use of @code{assume} +is optimization, as the compiler may be able to generate better code +if it assumes @var{E}. For best results, @var{E} should be simple +enough that a compiler can determine that it has no side effects: if +@var{E} calls an external function or accesses volatile storage the +compiler may not be able to optimize @var{E} away and @code{assume +(@var{E})} may therefore slow down the program. + +Here are some example uses of these macros. @example #include @@ -76,16 +96,24 @@ verify ((time_t) -1 < 0); verify (~ (time_t) -1 == 0); /* Return the maximum value of the integer type T, - verifying that T is an unsigned integer type. */ -#define MAX_UNSIGNED_VAL_WITH_COMMA(t) \ - (verify_true (0 < (T) -1), (T) -1) - -/* Same as MAX_UNSIGNED_VAL_WITH_COMMA, - but expand to an integer constant expression, - which cannot contain a comma operator. - The cast to (T) is outside the conditional expression + verifying that T is an unsigned integer type. + The cast to (T) is outside the call to verify_expr so that the result is of type T even when T is narrower than unsigned int. */ -#define MAX_UNSIGNED_VAL(t) ((T) \ - ((T) (verify_true (0 < (T) -1) ? -1 : 0)) +#define MAX_UNSIGNED_VAL(t) \ + ((T) verify_expr (0 < (T) -1, -1)) + +/* Return T divided by CHAR_MAX + 1, where behavior is + undefined if T < 0. In the common case where CHAR_MAX + is 127 the compiler can therefore implement the division + by shifting T right 7 bits, an optimization that would + not be valid if T were negative. */ +time_t +time_index (time_t t) +@{ + assume (0 <= t); + return t / (CHAR_MAX + 1); +@} + + @end example