346 lines
15 KiB
HTML
346 lines
15 KiB
HTML
<!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;
|
|
}
|
|
</script>
|
|
</div>
|
|
<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>
|