~ubuntu-branches/ubuntu/wily/sqlite3/wily

onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">

112

113

</form>

114

</div>

115

</table>

116

</div></div></div></div>

117

</td></tr></table>

118

119

120

<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Mutexes</h2><blockquote><pre>sqlite3_mutex *sqlite3_mutex_alloc(int);

121

void sqlite3_mutex_free(sqlite3_mutex*);

122

void sqlite3_mutex_enter(sqlite3_mutex*);

123

int sqlite3_mutex_try(sqlite3_mutex*);

124

void sqlite3_mutex_leave(sqlite3_mutex*);

125

</pre></blockquote><p>

126

The SQLite core uses these routines for thread

127

synchronization. Though they are intended for internal

128

use by SQLite, code that links against SQLite is

129

permitted to use any of these routines.</p>

130

131

<p>The SQLite source code contains multiple implementations

132

of these mutex routines. An appropriate implementation

133

is selected automatically at compile-time. The following

134

implementations are available in the SQLite core:</p>

135

136

<p><ul>

137

<li> SQLITE_MUTEX_OS2

138

<li> SQLITE_MUTEX_PTHREADS

139

<li> SQLITE_MUTEX_W32

140

<li> SQLITE_MUTEX_NOOP

141

</ul></p>

142

143

<p>The SQLITE_MUTEX_NOOP implementation is a set of routines

144

that does no real locking and is appropriate for use in

145

a single-threaded application. The SQLITE_MUTEX_OS2,

146

SQLITE_MUTEX_PTHREADS, and SQLITE_MUTEX_W32 implementations

147

are appropriate for use on OS/2, Unix, and Windows.</p>

148

149

<p>If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor

150

macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex

151

implementation is included with the library. In this case the

152

application must supply a custom mutex implementation using the

153

<a href="../c3ref/c_config_getmalloc.html#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a> option of the sqlite3_config() function

154

before calling sqlite3_initialize() or any other public sqlite3_

155

function that calls sqlite3_initialize().</p>

156

157

<p>The sqlite3_mutex_alloc() routine allocates a new

158

mutex and returns a pointer to it. If it returns NULL

159

that means that a mutex could not be allocated. SQLite

160

will unwind its stack and return an error. The argument

161

to sqlite3_mutex_alloc() is one of these integer constants:</p>

162

163

<p><ul>

164

<li> SQLITE_MUTEX_FAST

165

<li> SQLITE_MUTEX_RECURSIVE

166

<li> SQLITE_MUTEX_STATIC_MASTER

167

<li> SQLITE_MUTEX_STATIC_MEM

168

<li> SQLITE_MUTEX_STATIC_MEM2

169

<li> SQLITE_MUTEX_STATIC_PRNG

170

<li> SQLITE_MUTEX_STATIC_LRU

171

<li> SQLITE_MUTEX_STATIC_LRU2

172

</ul></p>

173

174

<p>The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)

175

cause sqlite3_mutex_alloc() to create

176

a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE

177

is used but not necessarily so when SQLITE_MUTEX_FAST is used.

178

The mutex implementation does not need to make a distinction

179

between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does

180

not want to. SQLite will only request a recursive mutex in

181

cases where it really needs one. If a faster non-recursive mutex

182

implementation is available on the host platform, the mutex subsystem

183

might return such a mutex in response to SQLITE_MUTEX_FAST.</p>

184

185

<p>The other allowed parameters to sqlite3_mutex_alloc() (anything other

186

than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return

187

a pointer to a static preexisting mutex. Six static mutexes are

188

used by the current version of SQLite. Future versions of SQLite

189

may add additional static mutexes. Static mutexes are for internal

190

use by SQLite only. Applications that use SQLite mutexes should

191

use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or

192

SQLITE_MUTEX_RECURSIVE.</p>

193

194

<p>Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST

195

or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()

196

returns a different mutex on every call. But for the static

197

mutex types, the same mutex is returned on every call that has

198

the same type number.</p>

199

200

<p>The sqlite3_mutex_free() routine deallocates a previously

201

allocated dynamic mutex. SQLite is careful to deallocate every

202

dynamic mutex that it allocates. The dynamic mutexes must not be in

203

use when they are deallocated. Attempting to deallocate a static

204

mutex results in undefined behavior. SQLite never deallocates

205

a static mutex.</p>

206

207

<p>The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt

208

to enter a mutex. If another thread is already within the mutex,

209

sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return

210

SQLITE_BUSY. The sqlite3_mutex_try() interface returns <a href="../c3ref/c_abort.html">SQLITE_OK</a>

211

upon successful entry. Mutexes created using

212

SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.

213

In such cases the,

214

mutex must be exited an equal number of times before another thread

215

can enter. If the same thread tries to enter any other

216

kind of mutex more than once, the behavior is undefined.

217

SQLite will never exhibit

218

such behavior in its own use of mutexes.</p>

219

220

<p>Some systems (for example, Windows 95) do not support the operation

221

implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()

222

will always return SQLITE_BUSY. The SQLite core only ever uses

223

sqlite3_mutex_try() as an optimization so this is acceptable behavior.</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. SQLite will

229

never do either.</p>

230

231

<p>If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or

232

sqlite3_mutex_leave() is a NULL pointer, then all three routines

233

behave as no-ops.</p>

234

235

<p>See also: <a href="../c3ref/mutex_held.html">sqlite3_mutex_held()</a> and <a href="../c3ref/mutex_held.html">sqlite3_mutex_notheld()</a>.

236

</p><p>See also lists of

237

<a href="objlist.html">Objects</a>,

238

<a href="constlist.html">Constants</a>, and

239

<a href="funclist.html">Functions</a>.</p>