Debian Codegraph @

www/threadsafe.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>Using SQLite In Multi-Threaded Applications</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 Using SQLite In Multi-Threaded Applications
122 </div>
123 </div>
124
125
126
127
128
129 <h1 id="overview"><span>1. </span>Overview</h1>
130
131 <p>SQLite supports three different threading modes:</p>
132
133 <ol>
134 <li><p><b>Single-thread</b>.
135 In this mode, all mutexes are disabled and SQLite is unsafe to use in
136 more than a single thread at once.</p></li>
137
138 <li><p><b>Multi-thread</b>.
139 In this mode, SQLite can be safely used by multiple threads provided that
140 no single <a href="c3ref/sqlite3.html">database connection</a> nor any object derived from database connection,
141 such as a <a href="c3ref/stmt.html">prepared statement</a>,
142 is used in two or more threads at the same time.
143 </p></li>
144
145 <li><p><b>Serialized</b>.
146 In serialized mode, API calls to affect or use any SQLite <a href="c3ref/sqlite3.html">database connection</a>
147 or any object derived from such a database connection
148 can be made safely from multiple threads.
149 The effect on an individual object is the same as if the API calls had all
150 been made in the same order from a single thread. The name "serialized"
151 arises from the fact that SQLite uses mutexes to serialize access to each
152 object.</p></li>
153 </ol>
154
155 <p>
156 The threading mode can be selected at compile-time (when the SQLite
157 library is being compiled from source code) or at start-time (when the
158 application that intends to use SQLite is initializing) or at
159 run-time (when a new SQLite database connection is being created).
160 Generally speaking, run-time overrides start-time and start-time
161 overrides compile-time. Except, single-thread mode cannot be
162 overridden once selected.
163 </p>
164
165 <p>
166 The default mode is serialized.
167 </p>
168
169 <h1 id="compile_time_selection_of_threading_mode"><span>2. </span>Compile-time selection of threading mode</h1>
170
171 <p>
172 Use the <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> compile-time parameter to select the
173 threading mode. If no <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> compile-time parameter is
174 present, then serialized mode is used.
175 This can be made explicit with
176 <a href="compile.html#threadsafe">-DSQLITE_THREADSAFE=1</a>.
177 With
178 <a href="compile.html#threadsafe">-DSQLITE_THREADSAFE=0</a> the threading mode is
179 single-thread. With
180 <a href="compile.html#threadsafe">-DSQLITE_THREADSAFE=2</a> the threading mode is
181 multi-thread.
182 </p>
183
184 <p>
185 The return value of the <a href="c3ref/threadsafe.html">sqlite3_threadsafe()</a> interface is the value
186 of SQLITE_THREADSAFE set at compile-time. It does not reflect changes
187 to the threading mode made at runtime via the <a href="c3ref/config.html">sqlite3_config()</a>
188 interface or by flags given as the third argument to <a href="c3ref/open.html">sqlite3_open_v2()</a>.
189 </p>
190
191 <p>
192 If single-thread mode is selected at compile-time, then critical
193 mutexing logic is omitted from the build and it is impossible to
194 enable either multi-thread or serialized modes at start-time or
195 run-time.
196 </p>
197
198 <h1 id="start_time_selection_of_threading_mode"><span>3. </span>Start-time selection of threading mode</h1>
199
200 <p>
201 Assuming that the compile-time threading mode is not single-thread, then
202 the threading mode can be changed during initialization using the
203 <a href="c3ref/config.html">sqlite3_config()</a> interface. The <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a> verb
204 puts SQLite into single-thread mode, the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a>
205 verb sets multi-thread mode, and the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigserialized">SQLITE_CONFIG_SERIALIZED</a> verb
206 sets serialized mode.
207 </p>
208
209 <h1 id="run_time_selection_of_threading_mode"><span>4. </span>Run-time selection of threading mode</h1>
210
211 <p>If single-thread mode has not been selected at compile-time or start-time,
212 then individual database connections can be created as either multi-thread
213 or serialized. It is not possible to downgrade an individual database
214 connection to single-thread mode. Nor is it possible to escalate an
215 individual database connection if the compile-time or start-time mode
216 is single-thread.</p>
217
218 <p>The threading mode for an individual database connection is determined
219 by flags given as the third argument to <a href="c3ref/open.html">sqlite3_open_v2()</a>. The
220 <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOMUTEX</a> flag causes the database connection to be in the
221 multi-thread mode and the <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_FULLMUTEX</a> flag causes the connection
222 to be in serialized mode. If neither flag is specified or if
223 <a href="c3ref/open.html">sqlite3_open()</a> or <a href="c3ref/open.html">sqlite3_open16()</a> are used instead of
224 <a href="c3ref/open.html">sqlite3_open_v2()</a>, then the default
225 mode determined by the compile-time and start-time settings is used.
226 </p>
227
228