1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="sqlite.css" rel="stylesheet">
<title>The Use Of assert() In SQLite</title>
<!-- path= -->
</head>
<body>
<div class=nosearch>
<a href="index.html">
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='about.html'>About</a>
<li class='desktoponly'><a href="docs.html">Documentation</a>
<li class='desktoponly'><a href="download.html">Download</a>
<li class='wideonly'><a href='copyright.html'>License</a>
<li class='desktoponly'><a href="support.html">Support</a>
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='about.html'>About</a>
<li><a href='docs.html'>Documentation</a>
<li><a href='download.html'>Download</a>
<li><a href='support.html'>Support</a>
<li><a href='prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<div class=fancy>
<div class=nosearch>
<div class="fancy_title">
The Use Of assert() In SQLite
</div>
<div class="fancy_toc">
<a onclick="toggle_toc()">
<span class="fancy_toc_mark" id="toc_mk">►</span>
Table Of Contents
</a>
<div id="toc_sub"><div class="fancy-toc1"><a href="#assert_and_similar_macros_in_sqlite">1. Assert() And Similar Macros In SQLite</a></div>
<div class="fancy-toc2"><a href="#philosophy_of_assert_">1.1. Philosophy of assert()</a></div>
<div class="fancy-toc2"><a href="#different_behaviors_according_to_build_type">1.2. Different Behaviors According To Build Type</a></div>
<div class="fancy-toc1"><a href="#examples">2. Examples</a></div>
</div>
</div>
<script>
function toggle_toc(){
var sub = document.getElementById("toc_sub")
var mk = document.getElementById("toc_mk")
if( sub.style.display!="block" ){
sub.style.display = "block";
mk.innerHTML = "▼";
} else {
sub.style.display = "none";
mk.innerHTML = "►";
}
}
</script>
</div>
<h1 id="assert_and_similar_macros_in_sqlite"><span>1. </span>Assert() And Similar Macros In SQLite</h1>
<p>
The assert(X) macro is
<a href="https://en.wikipedia.org/wiki/Assert.h">part of standard C</a>, in the
<assert.h> header file.
SQLite adds three other assert()-like macros named NEVER(X), ALWAYS(X),
and testcase(X).
</p><ul>
<li><p><b>assert(X)</b> →
The assert(X) statement indicates that the condition X is always true.
In other words, X is an invariant. The assert(X) macro works like a
procedure in that it has no return value.
</p></li><li><p><b>ALWAYS(X)</b> →
The ALWAYS(X) function indicates that condition X is always true as far
as the developers know, but there is no proof the X is true, or the
proof is complex and error-prone, or the proof depends on implementation
details that are likely to change in the future. ALWAYS(X) behaves like
a function that returns the boolean value X, and is intended to be used
within the conditional of an "if" statement.
</p></li><li><p><b>NEVER(X)</b> →
The NEVER(X) function indicates that condition X is never true. This
is the negative analog of the ALWAYS(X) function.
</p></li><li><p><b>testcase(X)</b> →
The testcase(X) statement indicates that X is sometimes true and sometimes
false. In other words, testcase(X) indicates that X is definitely not an
invariant. Since SQLite uses 100% <a href="testing.html#mcdc">MC/DC testing</a>, the presence of a
testcase(X) macro indicates that not only is it possible for X to be either
true or false, but there are test cases to demonstrate this.
</p></li></ul>
<p>
SQLite version 3.22.0 (2018-01-22) contains 5290 assert() macros,
839 testcase() macros, 88 ALWAYS() macros, and 63 NEVER() macros.
</p><h2 id="philosophy_of_assert_"><span>1.1. </span>Philosophy of assert()</h2>
<p>In SQLite, the presence of assert(X) means that the developers have
a proof that X is always true. Readers can depend upon X being true to
help them reason about the code. An assert(X) is a strong statement
about the truth of X. There is no doubt.
</p><p>The ALWAYS(X) and NEVER(X) macros are a weaker statement about the
truth of X. The presence of ALWAYS(X) or NEVER(X) means that the developers
believe X is always or never true, but there is no proof, or the proof
is complex and error-prone, or the proof depends on other aspects
of the system that seem likely to change.
</p><p>Other systems sometimes use assert(X) in a way that is
similar to the use of ALWAYS(X) or NEVER(X) in SQLite.
Developers will add an assert(X) as a
<a href="https://blog.regehr.org/archives/1576">tacit acknowledgement that they
do not fully believe that X is always true</a>.
We believe that this use of assert(X) is wrong and violates the intent
and purpose of having assert(X) available in C in the first place.
An assert(X) should not be seen as a safety-net or top-rope used to
guard against mistakes. Nor is assert(X) appropriate for defense-in-depth.
An ALWAYS(X) or NEVER(X) macro, or something similar, should be used in
those cases because ALWAYS(X) or NEVER(X) will be followed by code to
actually deal with the problem when the programmers reasoning
turns out to be wrong. Since the code that follows ALWAYS(X) or NEVER(X)
is untested, it should be something very simple, like a "return" statement,
that is easily verified by inspection.
</p><p>
Because assert() can be and is commonly misused, some programming language
theorists and designers look upon it with disfavor.
For example, the designers of the <a href="https://golang.org">Go programming language</a>
intentionally <a href="https://golang.org/doc/faq#assertions">omit a built-in assert()</a>.
They feel that the harm caused by misuse of assert()
outweighs the benefits of including it as a language built-in.
The SQLite developers disagree. In fact, the original purpose of this
article is to push back against the common notion that assert() is harmful.
In our experience, SQLite would be much more difficult to develop, test,
and maintain without assert().
</p><h2 id="different_behaviors_according_to_build_type"><span>1.2. </span>Different Behaviors According To Build Type</h2>
<p>Three separate builds are used to validate the SQLite software.
</p><ol>
<li> A functionality testing build is used to validate the source code.
</li><li> A coverage testing build is used to validate the test suite, to confirm
that the test suite provides 100% MC/DC.
</li><li> The release build is used to validate the generated machine code.
</li></ol>
<p>All tests must give the same answer in all three
builds. See the <a href="testing.html">"How SQLite Is Tested"</a> document for more detail.
</p><p>The various assert()-like
macros behave differently according to how SQLite is built.
</p><table striped="1" style="margin:1em auto; width:80%; border-spacing:0">
<tr style="text-align:left"><th></th><th>Functionality Testing</th><th>Coverage Testing</th><th>Release</th></tr>
<tr style="text-align:left;background-color:#DDDDDD"><th valign="top">assert(X)
</th><td>abort() if X is false
</td><td>no-op
</td><td>no-op
</td></tr>
<tr style="text-align:left"><th valign="top">ALWAYS(X)
</th><td>abort() if X is false
</td><td>always true
</td><td>pass through the value X
</td></tr>
<tr style="text-align:left;background-color:#DDDDDD"><th valign="top">NEVER(X)
</th><td>abort() if X is true
</td><td>always false
</td><td>pass through the value X
</td></tr>
<tr style="text-align:left"><th valign="top">testcase(X)
</th><td>no-op
</td><td>do some harmless work if X is true
</td><td>no-op
</td></tr>
</table>
<p>The default behavior of assert(X) in standard C is that it is enabled
for release builds. This is a reasonable default. However, the
SQLite code base has many assert() statements in performance-sensitive
areas of the code. Leaving assert(X) turned on causes SQLite to run about
three times slower. Also, SQLite strives to provide 100% MC/DC in an
as-delivered configuration, which is obviously impossible if assert(X)
statements are enabled. For these reasons, assert(X) is a no-op for
release builds in SQLite.
</p><p>The ALWAYS(X) and NEVER(X) macros behave like assert(X) during
functionality testing, because the developers want to be immediately
alerted to the issue if the value of X is different from what is expected.
But for delivery, ALWAYS(X) and NEVER(X) are simple pass-through macros,
which provide defense-in-depth. For coverage testing ALWAYS(X) and NEVER(X)
are hard-coded boolean values so that they do not cause unreachable
machine code to be generated.
</p><p>The testcase(X) macro is normally a no-op, but for a coverage test
build it does generate a small amount of extra code that includes at least
one branch, in order to verify that test cases exist for which X is both
true and false.
</p><h1 id="examples"><span>2. </span>Examples</h1>
<p>An assert() statement is often used to validate pre-conditions on
internal functions and methods.
Example: <a href="https://sqlite.org/src/artifact/c1e97e4c6f?ln=1048">https://sqlite.org/src/artifact/c1e97e4c6f?ln=1048</a>.
This is deemed better than simply stating the pre-condition in a header
comment, since the assert() is actually executed. In a highly tested
program like SQLite, the reader knows that the pre-condition is true
for all of the hundreds of millions of test cases run against SQLite,
since it has been verified by the assert().
In contrast, a text pre-condition statement in a header comment
is untested. It might have been true when the code was written,
but who is to say that it is still true now?
</p><p>
Sometimes SQLite uses compile-time evaluatable assert() statements.
Consider the code at
<a href="https://sqlite.org/src/artifact/c1e97e4c6f?ln=2130-2138">https://sqlite.org/src/artifact/c1e97e4c6f?ln=2130-2138</a>.
Four assert() statements verify the values for compile-time constants
so that the reader can quickly check the validity of the if-statement
that follows, without having to look up the constant values in a separate
header file.
</p><p>
Sometimes compile-time assert() statements are used to verify that
SQLite has been correctly compiled. For example, the code at
<a href="https://sqlite.org/src/artifact/c1e97e4c6f?ln=157">https://sqlite.org/src/artifact/c1e97e4c6f?ln=157</a>
verifies that the SQLITE_PTRSIZE preprocessor macro is set correctly
for the target architecture.
</p><p>
The CORRUPT_DB macro is used in many assert() statements.
In functional testing builds, CORRUPT_DB references a global variable
that is true if the database file might contain corruption. This variable
is true by default, since we do not normally know whether or not a database
is corrupt, but during testing while working on databases that are known
to be well-formed, that global variable can be set to false.
Then the CORRUPT_DB macro
can be used in assert() statements such as seen at
<a href="https://sqlite.org/src/artifact/18a53540aa3?ln=1679-1680">https://sqlite.org/src/artifact/18a53540aa3?ln=1679-1680</a>.
Those assert()s specify pre-conditions to the routine that are true for
consistent database files, but which might be false if the database file
is corrupt. Knowledge of these kinds of conditions is very helpful to
readers who are trying to understand a block of code in isolation.
</p><p>
ALWAYS(X) and NEVER(X) functions are used in places where we always
want the test to occur even though the developers believe the value of
X is always true or false. For example, the sqlite3BtreeCloseCursor()
routine shown must remove the closing cursor from a linked list of all
cursors. We know that the cursor is on the list, so that the loop
must terminate by the "break" statement, but it is convenient to
use the ALWAYS(X) test at
<a href="https://sqlite.org/src/artifact/18a53540aa3?ln=4371">https://sqlite.org/src/artifact/18a53540aa3?ln=4371</a> to prevent
running off the end of the linked list in case there is an error in some
other part of the code that has corrupted the linked list.
</p><p>
An ALWAYS(X) or NEVER(X) sometimes verifies pre-conditions that are
subject to change if other parts of the code are modified in
subtle ways. At <a href="https://sqlite.org/src/artifact/18a53540aa3?ln=5512-5516">https://sqlite.org/src/artifact/18a53540aa3?ln=5512-5516</a>
we have a test for two pre-conditions that are true only because
of the limited scope of use of the sqlite3BtreeRowCountEst() function.
Future enhancements to SQLite might use sqlite3BtreeRowCountEst() in
new ways where those preconditions no longer hold, and the NEVER()
macros will quickly alert the developers to that fact when the
situation arises. But if, for some reason, the pre-conditions are
not satisfied in a release build, the program will still behave sanely
and will not do an undefined memory access.
</p><p>
The testcase() macro is often used to verify that boundary
cases of an inequality comparison are checked. For example, at
<a href="https://sqlite.org/src/artifact/18a53540aa3?ln=5766">https://sqlite.org/src/artifact/18a53540aa3?ln=5766</a>. These
kind of checks help to prevent off-by-one errors.
</p><p align="center"><small><i>This page last modified on <a href="https://sqlite.org/docsrc/honeypot" id="mtimelink" data-href="https://sqlite.org/docsrc/finfo/pages/assert.in?m=abade93b77">2022-01-08 05:02:57</a> UTC </small></i></p>
|
