Simplifications to the implementation of the sum() SQL function.
[sqlite.git] / src / test_superlock.c
blob45d0d623a03b4cbf19ada28e754267b0b483e810
1 /*
2 ** 2010 November 19
3 **
4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
6 **
7 ** May you do good and not evil.
8 ** May you find forgiveness for yourself and forgive others.
9 ** May you share freely, never taking more than you give.
11 *************************************************************************
12 ** Example code for obtaining an exclusive lock on an SQLite database
13 ** file. This method is complicated, but works for both WAL and rollback
14 ** mode database files. The interface to the example code in this file
15 ** consists of the following two functions:
17 ** sqlite3demo_superlock()
18 ** sqlite3demo_superunlock()
21 #include "sqlite3.h"
22 #include <string.h> /* memset(), strlen() */
23 #include <assert.h> /* assert() */
26 ** A structure to collect a busy-handler callback and argument and a count
27 ** of the number of times it has been invoked.
29 struct SuperlockBusy {
30 int (*xBusy)(void*,int); /* Pointer to busy-handler function */
31 void *pBusyArg; /* First arg to pass to xBusy */
32 int nBusy; /* Number of times xBusy has been invoked */
34 typedef struct SuperlockBusy SuperlockBusy;
37 ** An instance of the following structure is allocated for each active
38 ** superlock. The opaque handle returned by sqlite3demo_superlock() is
39 ** actually a pointer to an instance of this structure.
41 struct Superlock {
42 sqlite3 *db; /* Database handle used to lock db */
43 int bWal; /* True if db is a WAL database */
45 typedef struct Superlock Superlock;
48 ** The pCtx pointer passed to this function is actually a pointer to a
49 ** SuperlockBusy structure. Invoke the busy-handler function encapsulated
50 ** by the structure and return the result.
52 static int superlockBusyHandler(void *pCtx, int UNUSED){
53 SuperlockBusy *pBusy = (SuperlockBusy *)pCtx;
54 if( pBusy->xBusy==0 ) return 0;
55 return pBusy->xBusy(pBusy->pBusyArg, pBusy->nBusy++);
59 ** This function is used to determine if the main database file for
60 ** connection db is open in WAL mode or not. If no error occurs and the
61 ** database file is in WAL mode, set *pbWal to true and return SQLITE_OK.
62 ** If it is not in WAL mode, set *pbWal to false.
64 ** If an error occurs, return an SQLite error code. The value of *pbWal
65 ** is undefined in this case.
67 static int superlockIsWal(Superlock *pLock){
68 int rc; /* Return Code */
69 sqlite3_stmt *pStmt; /* Compiled PRAGMA journal_mode statement */
71 rc = sqlite3_prepare(pLock->db, "PRAGMA main.journal_mode", -1, &pStmt, 0);
72 if( rc!=SQLITE_OK ) return rc;
74 pLock->bWal = 0;
75 if( SQLITE_ROW==sqlite3_step(pStmt) ){
76 const char *zMode = (const char *)sqlite3_column_text(pStmt, 0);
77 if( zMode && strlen(zMode)==3 && sqlite3_strnicmp("wal", zMode, 3)==0 ){
78 pLock->bWal = 1;
82 return sqlite3_finalize(pStmt);
86 ** Obtain an exclusive shm-lock on nByte bytes starting at offset idx
87 ** of the file fd. If the lock cannot be obtained immediately, invoke
88 ** the busy-handler until either it is obtained or the busy-handler
89 ** callback returns 0.
91 static int superlockShmLock(
92 sqlite3_file *fd, /* Database file handle */
93 int idx, /* Offset of shm-lock to obtain */
94 int nByte, /* Number of consective bytes to lock */
95 SuperlockBusy *pBusy /* Busy-handler wrapper object */
97 int rc;
98 int (*xShmLock)(sqlite3_file*, int, int, int) = fd->pMethods->xShmLock;
99 do {
100 rc = xShmLock(fd, idx, nByte, SQLITE_SHM_LOCK|SQLITE_SHM_EXCLUSIVE);
101 }while( rc==SQLITE_BUSY && superlockBusyHandler((void *)pBusy, 0) );
102 return rc;
106 ** Obtain the extra locks on the database file required for WAL databases.
107 ** Invoke the supplied busy-handler as required.
109 static int superlockWalLock(
110 sqlite3 *db, /* Database handle open on WAL database */
111 SuperlockBusy *pBusy /* Busy handler wrapper object */
113 int rc; /* Return code */
114 sqlite3_file *fd = 0; /* Main database file handle */
115 void volatile *p = 0; /* Pointer to first page of shared memory */
117 /* Obtain a pointer to the sqlite3_file object open on the main db file. */
118 rc = sqlite3_file_control(db, "main", SQLITE_FCNTL_FILE_POINTER, (void *)&fd);
119 if( rc!=SQLITE_OK ) return rc;
121 /* Obtain the "recovery" lock. Normally, this lock is only obtained by
122 ** clients running database recovery.
124 rc = superlockShmLock(fd, 2, 1, pBusy);
125 if( rc!=SQLITE_OK ) return rc;
127 /* Zero the start of the first shared-memory page. This means that any
128 ** clients that open read or write transactions from this point on will
129 ** have to run recovery before proceeding. Since they need the "recovery"
130 ** lock that this process is holding to do that, no new read or write
131 ** transactions may now be opened. Nor can a checkpoint be run, for the
132 ** same reason.
134 rc = fd->pMethods->xShmMap(fd, 0, 32*1024, 1, &p);
135 if( rc!=SQLITE_OK ) return rc;
136 memset((void *)p, 0, 32);
138 /* Obtain exclusive locks on all the "read-lock" slots. Once these locks
139 ** are held, it is guaranteed that there are no active reader, writer or
140 ** checkpointer clients.
142 rc = superlockShmLock(fd, 3, SQLITE_SHM_NLOCK-3, pBusy);
143 return rc;
147 ** Release a superlock held on a database file. The argument passed to
148 ** this function must have been obtained from a successful call to
149 ** sqlite3demo_superlock().
151 void sqlite3demo_superunlock(void *pLock){
152 Superlock *p = (Superlock *)pLock;
153 if( p->bWal ){
154 int rc; /* Return code */
155 int flags = SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE;
156 sqlite3_file *fd = 0;
157 rc = sqlite3_file_control(p->db, "main", SQLITE_FCNTL_FILE_POINTER, (void *)&fd);
158 if( rc==SQLITE_OK ){
159 fd->pMethods->xShmLock(fd, 2, 1, flags);
160 fd->pMethods->xShmLock(fd, 3, SQLITE_SHM_NLOCK-3, flags);
163 sqlite3_close(p->db);
164 sqlite3_free(p);
168 ** Obtain a superlock on the database file identified by zPath, using the
169 ** locking primitives provided by VFS zVfs. If successful, SQLITE_OK is
170 ** returned and output variable *ppLock is populated with an opaque handle
171 ** that may be used with sqlite3demo_superunlock() to release the lock.
173 ** If an error occurs, *ppLock is set to 0 and an SQLite error code
174 ** (e.g. SQLITE_BUSY) is returned.
176 ** If a required lock cannot be obtained immediately and the xBusy parameter
177 ** to this function is not NULL, then xBusy is invoked in the same way
178 ** as a busy-handler registered with SQLite (using sqlite3_busy_handler())
179 ** until either the lock can be obtained or the busy-handler function returns
180 ** 0 (indicating "give up").
182 int sqlite3demo_superlock(
183 const char *zPath, /* Path to database file to lock */
184 const char *zVfs, /* VFS to use to access database file */
185 int (*xBusy)(void*,int), /* Busy handler callback */
186 void *pBusyArg, /* Context arg for busy handler */
187 void **ppLock /* OUT: Context to pass to superunlock() */
189 SuperlockBusy busy = {0, 0, 0}; /* Busy handler wrapper object */
190 int rc; /* Return code */
191 Superlock *pLock;
193 pLock = sqlite3_malloc(sizeof(Superlock));
194 if( !pLock ) return SQLITE_NOMEM;
195 memset(pLock, 0, sizeof(Superlock));
197 /* Open a database handle on the file to superlock. */
198 rc = sqlite3_open_v2(
199 zPath, &pLock->db, SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE, zVfs
202 /* Install a busy-handler and execute a BEGIN EXCLUSIVE. If this is not
203 ** a WAL database, this is all we need to do.
205 ** A wrapper function is used to invoke the busy-handler instead of
206 ** registering the busy-handler function supplied by the user directly
207 ** with SQLite. This is because the same busy-handler function may be
208 ** invoked directly later on when attempting to obtain the extra locks
209 ** required in WAL mode. By using the wrapper, we are able to guarantee
210 ** that the "nBusy" integer parameter passed to the users busy-handler
211 ** represents the total number of busy-handler invocations made within
212 ** this call to sqlite3demo_superlock(), including any made during the
213 ** "BEGIN EXCLUSIVE".
215 if( rc==SQLITE_OK ){
216 busy.xBusy = xBusy;
217 busy.pBusyArg = pBusyArg;
218 sqlite3_busy_handler(pLock->db, superlockBusyHandler, (void *)&busy);
219 rc = sqlite3_exec(pLock->db, "BEGIN EXCLUSIVE", 0, 0, 0);
222 /* If the BEGIN EXCLUSIVE was executed successfully and this is a WAL
223 ** database, call superlockWalLock() to obtain the extra locks required
224 ** to prevent readers, writers and/or checkpointers from accessing the
225 ** db while this process is holding the superlock.
227 ** Before attempting any WAL locks, commit the transaction started above
228 ** to drop the WAL read and write locks currently held. Otherwise, the
229 ** new WAL locks may conflict with the old.
231 if( rc==SQLITE_OK ){
232 if( SQLITE_OK==(rc = superlockIsWal(pLock)) && pLock->bWal ){
233 rc = sqlite3_exec(pLock->db, "COMMIT", 0, 0, 0);
234 if( rc==SQLITE_OK ){
235 rc = superlockWalLock(pLock->db, &busy);
240 if( rc!=SQLITE_OK ){
241 sqlite3demo_superunlock(pLock);
242 *ppLock = 0;
243 }else{
244 *ppLock = pLock;
247 return rc;
251 ** End of example code. Everything below here is the test harness.
252 **************************************************************************
253 **************************************************************************
254 *************************************************************************/
257 #ifdef SQLITE_TEST
259 #if defined(INCLUDE_SQLITE_TCL_H)
260 # include "sqlite_tcl.h"
261 #else
262 # include "tcl.h"
263 # ifndef SQLITE_TCLAPI
264 # define SQLITE_TCLAPI
265 # endif
266 #endif
268 struct InterpAndScript {
269 Tcl_Interp *interp;
270 Tcl_Obj *pScript;
272 typedef struct InterpAndScript InterpAndScript;
274 static void SQLITE_TCLAPI superunlock_del(ClientData cd){
275 sqlite3demo_superunlock((void *)cd);
278 static int SQLITE_TCLAPI superunlock_cmd(
279 ClientData cd,
280 Tcl_Interp *interp,
281 int objc,
282 Tcl_Obj *CONST objv[]
284 if( objc!=1 ){
285 Tcl_WrongNumArgs(interp, 1, objv, "");
286 return TCL_ERROR;
288 Tcl_DeleteCommand(interp, Tcl_GetString(objv[0]));
289 return TCL_OK;
292 static int superlock_busy(void *pCtx, int nBusy){
293 InterpAndScript *p = (InterpAndScript *)pCtx;
294 Tcl_Obj *pEval; /* Script to evaluate */
295 int iVal = 0; /* Value to return */
297 pEval = Tcl_DuplicateObj(p->pScript);
298 Tcl_IncrRefCount(pEval);
299 Tcl_ListObjAppendElement(p->interp, pEval, Tcl_NewIntObj(nBusy));
300 Tcl_EvalObjEx(p->interp, pEval, TCL_EVAL_GLOBAL);
301 Tcl_GetIntFromObj(p->interp, Tcl_GetObjResult(p->interp), &iVal);
302 Tcl_DecrRefCount(pEval);
304 return iVal;
308 ** Tclcmd: sqlite3demo_superlock CMDNAME PATH VFS BUSY-HANDLER-SCRIPT
310 static int SQLITE_TCLAPI superlock_cmd(
311 ClientData cd,
312 Tcl_Interp *interp,
313 int objc,
314 Tcl_Obj *CONST objv[]
316 void *pLock; /* Lock context */
317 char *zPath;
318 char *zVfs = 0;
319 InterpAndScript busy = {0, 0};
320 int (*xBusy)(void*,int) = 0; /* Busy handler callback */
321 int rc; /* Return code from sqlite3demo_superlock() */
323 if( objc<3 || objc>5 ){
324 Tcl_WrongNumArgs(
325 interp, 1, objv, "CMDNAME PATH ?VFS? ?BUSY-HANDLER-SCRIPT?");
326 return TCL_ERROR;
329 zPath = Tcl_GetString(objv[2]);
331 if( objc>3 ){
332 zVfs = Tcl_GetString(objv[3]);
333 if( strlen(zVfs)==0 ) zVfs = 0;
335 if( objc>4 ){
336 busy.interp = interp;
337 busy.pScript = objv[4];
338 xBusy = superlock_busy;
341 rc = sqlite3demo_superlock(zPath, zVfs, xBusy, &busy, &pLock);
342 assert( rc==SQLITE_OK || pLock==0 );
343 assert( rc!=SQLITE_OK || pLock!=0 );
345 if( rc!=SQLITE_OK ){
346 extern const char *sqlite3ErrStr(int);
347 Tcl_ResetResult(interp);
348 Tcl_AppendResult(interp, sqlite3ErrStr(rc), 0);
349 return TCL_ERROR;
352 Tcl_CreateObjCommand(
353 interp, Tcl_GetString(objv[1]), superunlock_cmd, pLock, superunlock_del
355 Tcl_SetObjResult(interp, objv[1]);
356 return TCL_OK;
359 int SqliteSuperlock_Init(Tcl_Interp *interp){
360 Tcl_CreateObjCommand(interp, "sqlite3demo_superlock", superlock_cmd, 0, 0);
361 return TCL_OK;
363 #endif