diff options
Diffstat (limited to 'www/assert.html')
| -rw-r--r-- | www/assert.html | 370 |
1 files changed, 370 insertions, 0 deletions
diff --git a/www/assert.html b/www/assert.html new file mode 100644 index 0000000..52d1959 --- /dev/null +++ b/www/assert.html @@ -0,0 +1,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> + |