Debian Codegraph @

www/c3ref/mutex_alloc.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>Mutexes</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 <!-- keywords: sqlite3_mutex_alloc sqlite3_mutex_enter sqlite3_mutex_free sqlite3_mutex_leave sqlite3_mutex_try -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Mutexes</h2>
122 </div>
123 <blockquote><pre>
124 sqlite3_mutex *sqlite3_mutex_alloc(int);
125 void sqlite3_mutex_free(sqlite3_mutex*);
126 void sqlite3_mutex_enter(sqlite3_mutex*);
127 int sqlite3_mutex_try(sqlite3_mutex*);
128 void sqlite3_mutex_leave(sqlite3_mutex*);
129 </pre></blockquote>
130 <p>
131 The SQLite core uses these routines for thread
132 synchronization. Though they are intended for internal
133 use by SQLite, code that links against SQLite is
134 permitted to use any of these routines.</p>
135
136 <p>The SQLite source code contains multiple implementations
137 of these mutex routines. An appropriate implementation
138 is selected automatically at compile-time. The following
139 implementations are available in the SQLite core:</p>
140
141 <p><ul>
142 <li> SQLITE_MUTEX_PTHREADS
143 <li> SQLITE_MUTEX_W32
144 <li> SQLITE_MUTEX_NOOP
145 </ul></p>
146
147 <p>The SQLITE_MUTEX_NOOP implementation is a set of routines
148 that does no real locking and is appropriate for use in
149 a single-threaded application. The SQLITE_MUTEX_PTHREADS and
150 SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
151 and Windows.</p>
152
153 <p>The sqlite3_mutex_alloc() routine allocates a new
154 mutex and returns a pointer to it. The sqlite3_mutex_alloc()
155 routine returns NULL if it is unable to allocate the requested
156 mutex. The argument to sqlite3_mutex_alloc() must be one of these
157 integer constants:</p>
158
159 <p><ul>
160 <li> SQLITE_MUTEX_FAST
161 <li> SQLITE_MUTEX_RECURSIVE
162 <li> SQLITE_MUTEX_STATIC_MAIN
163 <li> SQLITE_MUTEX_STATIC_MEM
164 <li> SQLITE_MUTEX_STATIC_OPEN
165 <li> SQLITE_MUTEX_STATIC_PRNG
166 <li> SQLITE_MUTEX_STATIC_LRU
167 <li> SQLITE_MUTEX_STATIC_PMEM
168 <li> SQLITE_MUTEX_STATIC_APP1
169 <li> SQLITE_MUTEX_STATIC_APP2
170 <li> SQLITE_MUTEX_STATIC_APP3
171 <li> SQLITE_MUTEX_STATIC_VFS1
172 <li> SQLITE_MUTEX_STATIC_VFS2
173 <li> SQLITE_MUTEX_STATIC_VFS3
174 </ul></p>
175
176 <p>The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
177 cause sqlite3_mutex_alloc() to create
178 a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
179 is used but not necessarily so when SQLITE_MUTEX_FAST is used.
180 The mutex implementation does not need to make a distinction
181 between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
182 not want to. SQLite will only request a recursive mutex in
183 cases where it really needs one. If a faster non-recursive mutex
184 implementation is available on the host platform, the mutex subsystem
185 might return such a mutex in response to SQLITE_MUTEX_FAST.</p>
186
187 <p>The other allowed parameters to sqlite3_mutex_alloc() (anything other
188 than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
189 a pointer to a static preexisting mutex. Nine static mutexes are
190 used by the current version of SQLite. Future versions of SQLite
191 may add additional static mutexes. Static mutexes are for internal
192 use by SQLite only. Applications that use SQLite mutexes should
193 use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
194 SQLITE_MUTEX_RECURSIVE.</p>
195
196 <p>Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
197 or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
198 returns a different mutex on every call. For the static
199 mutex types, the same mutex is returned on every call that has
200 the same type number.</p>
201
202 <p>The sqlite3_mutex_free() routine deallocates a previously
203 allocated dynamic mutex. Attempting to deallocate a static
204 mutex results in undefined behavior.</p>
205
206 <p>The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
207 to enter a mutex. If another thread is already within the mutex,
208 sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
209 SQLITE_BUSY. The sqlite3_mutex_try() interface returns <a href="../rescode.html#ok">SQLITE_OK</a>
210 upon successful entry. Mutexes created using
211 SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
212 In such cases, the
213 mutex must be exited an equal number of times before another thread
214 can enter. If the same thread tries to enter any mutex other
215 than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.</p>
216
217 <p>Some systems (for example, Windows 95) do not support the operation
218 implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
219 will always return SQLITE_BUSY. In most cases the SQLite core only uses
220 sqlite3_mutex_try() as an optimization, so this is acceptable
221 behavior. The exceptions are unix builds that set the
222 SQLITE_ENABLE_SETLK_TIMEOUT build option. In that case a working
223 sqlite3_mutex_try() is required.</p>
224
225 <p>The sqlite3_mutex_leave() routine exits a mutex that was
226 previously entered by the same thread. The behavior
227 is undefined if the mutex is not currently entered by the
228 calling thread or is not currently allocated.</p>
229
230 <p>If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(),
231 sqlite3_mutex_leave(), or sqlite3_mutex_free() is a NULL pointer,
232 then any of the four routines behaves as a no-op.</p>
233
234 <p>See also: <a href="../c3ref/mutex_held.html">sqlite3_mutex_held()</a> and <a href="../c3ref/mutex_held.html">sqlite3_mutex_notheld()</a>.
235 </p><p>See also lists of
236 <a href="../c3ref/objlist.html">Objects</a>,
237 <a href="../c3ref/constlist.html">Constants</a>, and
238 <a href="../c3ref/funclist.html">Functions</a>.</p>
239