Debian Codegraph @

www/c3ref/mutex_methods.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>Mutex Methods Object</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_methods -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Mutex Methods Object</h2>
122 </div>
123 <blockquote><pre>
124 typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
125 struct sqlite3_mutex_methods {
126 int (*xMutexInit)(void);
127 int (*xMutexEnd)(void);
128 sqlite3_mutex *(*xMutexAlloc)(int);
129 void (*xMutexFree)(sqlite3_mutex *);
130 void (*xMutexEnter)(sqlite3_mutex *);
131 int (*xMutexTry)(sqlite3_mutex *);
132 void (*xMutexLeave)(sqlite3_mutex *);
133 int (*xMutexHeld)(sqlite3_mutex *);
134 int (*xMutexNotheld)(sqlite3_mutex *);
135 };
136 </pre></blockquote>
137 <p>
138 An instance of this structure defines the low-level routines
139 used to allocate and use mutexes.</p>
140
141 <p>Usually, the default mutex implementations provided by SQLite are
142 sufficient, however the application has the option of substituting a custom
143 implementation for specialized deployments or systems for which SQLite
144 does not provide a suitable implementation. In this case, the application
145 creates and populates an instance of this structure to pass
146 to sqlite3_config() along with the <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a> option.
147 Additionally, an instance of this structure can be used as an
148 output variable when querying the system for the current mutex
149 implementation, using the <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfiggetmutex">SQLITE_CONFIG_GETMUTEX</a> option.</p>
150
151 <p>The xMutexInit method defined by this structure is invoked as
152 part of system initialization by the sqlite3_initialize() function.
153 The xMutexInit routine is called by SQLite exactly once for each
154 effective call to <a href="../c3ref/initialize.html">sqlite3_initialize()</a>.</p>
155
156 <p>The xMutexEnd method defined by this structure is invoked as
157 part of system shutdown by the sqlite3_shutdown() function. The
158 implementation of this method is expected to release all outstanding
159 resources obtained by the mutex methods implementation, especially
160 those obtained by the xMutexInit method. The xMutexEnd()
161 interface is invoked exactly once for each call to <a href="../c3ref/initialize.html">sqlite3_shutdown()</a>.</p>
162
163 <p>The remaining seven methods defined by this structure (xMutexAlloc,
164 xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
165 xMutexNotheld) implement the following interfaces (respectively):</p>
166
167 <p><ul>
168 <li> <a href="../c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a> </li>
169 <li> <a href="../c3ref/mutex_alloc.html">sqlite3_mutex_free()</a> </li>
170 <li> <a href="../c3ref/mutex_alloc.html">sqlite3_mutex_enter()</a> </li>
171 <li> <a href="../c3ref/mutex_alloc.html">sqlite3_mutex_try()</a> </li>
172 <li> <a href="../c3ref/mutex_alloc.html">sqlite3_mutex_leave()</a> </li>
173 <li> <a href="../c3ref/mutex_held.html">sqlite3_mutex_held()</a> </li>
174 <li> <a href="../c3ref/mutex_held.html">sqlite3_mutex_notheld()</a> </li>
175 </ul></p>
176
177 <p>The only difference is that the public sqlite3_XXX functions enumerated
178 above silently ignore any invocations that pass a NULL pointer instead
179 of a valid mutex handle. The implementations of the methods defined
180 by this structure are not required to handle this case. The results
181 of passing a NULL pointer instead of a valid mutex handle are undefined
182 (i.e. it is acceptable to provide an implementation that segfaults if
183 it is passed a NULL pointer).</p>
184
185 <p>The xMutexInit() method must be threadsafe. It must be harmless to
186 invoke xMutexInit() multiple times within the same process and without
187 intervening calls to xMutexEnd(). Second and subsequent calls to
188 xMutexInit() must be no-ops.</p>
189
190 <p>xMutexInit() must not use SQLite memory allocation (<a href="../c3ref/free.html">sqlite3_malloc()</a>
191 and its associates). Similarly, xMutexAlloc() must not use SQLite memory
192 allocation for a static mutex. However xMutexAlloc() may use SQLite
193 memory allocation for a fast or recursive mutex.</p>
194
195 <p>SQLite will invoke the xMutexEnd() method when <a href="../c3ref/initialize.html">sqlite3_shutdown()</a> is
196 called, but only if the prior call to xMutexInit returned SQLITE_OK.
197 If xMutexInit fails in any way, it is expected to clean up after itself
198 prior to returning.
199 </p><p>See also lists of
200 <a href="../c3ref/objlist.html">Objects</a>,
201 <a href="../c3ref/constlist.html">Constants</a>, and
202 <a href="../c3ref/funclist.html">Functions</a>.</p>
203