Debian Codegraph @

www/assert.html

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