~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>Unlock Notification</h2><blockquote><pre>int sqlite3_unlock_notify(

121

sqlite3 *pBlocked, /* Waiting connection */

122

void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */

123

void *pNotifyArg /* Argument to pass to xNotify */

124

);

125

</pre></blockquote><p>

126

When running in shared-cache mode, a database operation may fail with

127

an <a href="../c3ref/c_abort.html">SQLITE_LOCKED</a> error if the required locks on the shared-cache or

128

individual tables within the shared-cache cannot be obtained. See

129

<a href="../sharedcache.html">SQLite Shared-Cache Mode</a> for a description of shared-cache locking.

130

This API may be used to register a callback that SQLite will invoke

131

when the connection currently holding the required lock relinquishes it.

132

This API is only available if the library was compiled with the

133

<a href="../compile.html#enable_unlock_notify">SQLITE_ENABLE_UNLOCK_NOTIFY</a> C-preprocessor symbol defined.</p>

134

135

<p>See Also: <a href="../unlock_notify.html">Using the SQLite Unlock Notification Feature</a>.</p>

136

137

<p>Shared-cache locks are released when a database connection concludes

138

its current transaction, either by committing it or rolling it back.</p>

139

140

<p>When a connection (known as the blocked connection) fails to obtain a

141

shared-cache lock and SQLITE_LOCKED is returned to the caller, the

142

identity of the database connection (the blocking connection) that

143

has locked the required resource is stored internally. After an

144

application receives an SQLITE_LOCKED error, it may call the

145

sqlite3_unlock_notify() method with the blocked connection handle as

146

the first argument to register for a callback that will be invoked

147

when the blocking connections current transaction is concluded. The

148

callback is invoked from within the <a href="../c3ref/step.html">sqlite3_step</a> or <a href="../c3ref/close.html">sqlite3_close</a>

149

call that concludes the blocking connections transaction.</p>

150

151

<p>If sqlite3_unlock_notify() is called in a multi-threaded application,

152

there is a chance that the blocking connection will have already

153

concluded its transaction by the time sqlite3_unlock_notify() is invoked.

154

If this happens, then the specified callback is invoked immediately,

155

from within the call to sqlite3_unlock_notify().</p>

156

157

<p>If the blocked connection is attempting to obtain a write-lock on a

158

shared-cache table, and more than one other connection currently holds

159

a read-lock on the same table, then SQLite arbitrarily selects one of

160

the other connections to use as the blocking connection.</p>

161

162

<p>There may be at most one unlock-notify callback registered by a

163

blocked connection. If sqlite3_unlock_notify() is called when the

164

blocked connection already has a registered unlock-notify callback,

165

then the new callback replaces the old. If sqlite3_unlock_notify() is

166

called with a NULL pointer as its second argument, then any existing

167

unlock-notify callback is canceled. The blocked connections

168

unlock-notify callback may also be canceled by closing the blocked

169

connection using <a href="../c3ref/close.html">sqlite3_close()</a>.</p>

170

171

<p>The unlock-notify callback is not reentrant. If an application invokes

172

any sqlite3_xxx API functions from within an unlock-notify callback, a

173

crash or deadlock may be the result.</p>

174

175

<p>Unless deadlock is detected (see below), sqlite3_unlock_notify() always

176

returns SQLITE_OK.</p>

177

178

<p><b>Callback Invocation Details</b></p>

179

180

<p>When an unlock-notify callback is registered, the application provides a

181

single void* pointer that is passed to the callback when it is invoked.

182

However, the signature of the callback function allows SQLite to pass

183

it an array of void* context pointers. The first argument passed to

184

an unlock-notify callback is a pointer to an array of void* pointers,

185

and the second is the number of entries in the array.</p>

186

187

<p>When a blocking connections transaction is concluded, there may be

188

more than one blocked connection that has registered for an unlock-notify

189

callback. If two or more such blocked connections have specified the

190

same callback function, then instead of invoking the callback function

191

multiple times, it is invoked once with the set of void* context pointers

192

specified by the blocked connections bundled together into an array.

193

This gives the application an opportunity to prioritize any actions

194

related to the set of unblocked database connections.</p>

195

196

<p><b>Deadlock Detection</b></p>

197

198

<p>Assuming that after registering for an unlock-notify callback a

199

database waits for the callback to be issued before taking any further

200

action (a reasonable assumption), then using this API may cause the

201

application to deadlock. For example, if connection X is waiting for

202

connection Y's transaction to be concluded, and similarly connection

203

Y is waiting on connection X's transaction, then neither connection

204

will proceed and the system may remain deadlocked indefinitely.</p>

205

206

<p>To avoid this scenario, the sqlite3_unlock_notify() performs deadlock

207

detection. If a given call to sqlite3_unlock_notify() would put the

208

system in a deadlocked state, then SQLITE_LOCKED is returned and no

209

unlock-notify callback is registered. The system is said to be in

210

a deadlocked state if connection A has registered for an unlock-notify

211

callback on the conclusion of connection B's transaction, and connection

212

B has itself registered for an unlock-notify callback when connection

213

A's transaction is concluded. Indirect deadlock is also detected, so

214

the system is also considered to be deadlocked if connection B has

215

registered for an unlock-notify callback on the conclusion of connection

216

C's transaction, where connection C is waiting on connection A. Any

217

number of levels of indirection are allowed.</p>

218

219

<p><b>The "DROP TABLE" Exception</b></p>

220

221

<p>When a call to <a href="../c3ref/step.html">sqlite3_step()</a> returns SQLITE_LOCKED, it is almost

222

always appropriate to call sqlite3_unlock_notify(). There is however,

223

one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,

224

SQLite checks if there are any currently executing SELECT statements

225

that belong to the same connection. If there are, SQLITE_LOCKED is

226

returned. In this case there is no "blocking connection", so invoking

227

sqlite3_unlock_notify() results in the unlock-notify callback being

228

invoked immediately. If the application then re-attempts the "DROP TABLE"

229

or "DROP INDEX" query, an infinite loop might be the result.</p>

230

231

<p>One way around this problem is to check the extended error code returned

232

by an sqlite3_step() call. If there is a blocking connection, then the

233

extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in

234

the special "DROP TABLE/INDEX" case, the extended error code is just

235

SQLITE_LOCKED.

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>