4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
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 *************************************************************************
13 ** This file contains the implementation of some Tcl commands used to
14 ** test that sqlite3 database handles may be concurrently accessed by
15 ** multiple threads. Right now this only works on unix.
18 #include "sqliteInt.h"
25 #if !defined(_MSC_VER)
30 ** One of these is allocated for each thread created by [sqlthread spawn].
32 typedef struct SqlThread SqlThread;
34 Tcl_ThreadId parent; /* Thread id of parent thread */
35 Tcl_Interp *interp; /* Parent interpreter */
36 char *zScript; /* The script to execute. */
37 char *zVarname; /* Varname in parent script */
41 ** A custom Tcl_Event type used by this module. When the event is
42 ** handled, script zScript is evaluated in interpreter interp. If
43 ** the evaluation throws an exception (returns TCL_ERROR), then the
44 ** error is handled by Tcl_BackgroundError(). If no error occurs,
45 ** the result is simply discarded.
47 typedef struct EvalEvent EvalEvent;
49 Tcl_Event base; /* Base class of type Tcl_Event */
50 char *zScript; /* The script to execute. */
51 Tcl_Interp *interp; /* The interpreter to execute it in. */
54 static Tcl_ObjCmdProc sqlthread_proc;
55 static Tcl_ObjCmdProc clock_seconds_proc;
56 #if SQLITE_OS_UNIX && defined(SQLITE_ENABLE_UNLOCK_NOTIFY)
57 static Tcl_ObjCmdProc blocking_step_proc;
58 static Tcl_ObjCmdProc blocking_prepare_v2_proc;
60 int Sqlitetest1_Init(Tcl_Interp *);
61 int Sqlite3_Init(Tcl_Interp *);
63 /* Functions from test1.c */
64 void *sqlite3TestTextToPtr(const char *);
65 const char *sqlite3TestErrorName(int);
66 int getDbPointer(Tcl_Interp *, const char *, sqlite3 **);
67 int sqlite3TestMakePointerStr(Tcl_Interp *, char *, void *);
68 int sqlite3TestErrCode(Tcl_Interp *, sqlite3 *, int);
71 ** Handler for events of type EvalEvent.
73 static int tclScriptEvent(Tcl_Event *evPtr, int flags){
75 EvalEvent *p = (EvalEvent *)evPtr;
76 rc = Tcl_Eval(p->interp, p->zScript);
78 Tcl_BackgroundError(p->interp);
80 UNUSED_PARAMETER(flags);
85 ** Register an EvalEvent to evaluate the script pScript in the
86 ** parent interpreter/thread of SqlThread p.
88 static void postToParent(SqlThread *p, Tcl_Obj *pScript){
93 zMsg = Tcl_GetStringFromObj(pScript, &nMsg);
94 pEvent = (EvalEvent *)ckalloc(sizeof(EvalEvent)+nMsg+1);
95 pEvent->base.nextPtr = 0;
96 pEvent->base.proc = tclScriptEvent;
97 pEvent->zScript = (char *)&pEvent[1];
98 memcpy(pEvent->zScript, zMsg, nMsg+1);
99 pEvent->interp = p->interp;
101 Tcl_ThreadQueueEvent(p->parent, (Tcl_Event *)pEvent, TCL_QUEUE_TAIL);
102 Tcl_ThreadAlert(p->parent);
106 ** The main function for threads created with [sqlthread spawn].
108 static Tcl_ThreadCreateType tclScriptThread(ClientData pSqlThread){
113 SqlThread *p = (SqlThread *)pSqlThread;
114 extern int Sqlitetest_mutex_Init(Tcl_Interp*);
116 interp = Tcl_CreateInterp();
117 Tcl_CreateObjCommand(interp, "clock_seconds", clock_seconds_proc, 0, 0);
118 Tcl_CreateObjCommand(interp, "sqlthread", sqlthread_proc, pSqlThread, 0);
119 #if SQLITE_OS_UNIX && defined(SQLITE_ENABLE_UNLOCK_NOTIFY)
120 Tcl_CreateObjCommand(interp, "sqlite3_blocking_step", blocking_step_proc,0,0);
121 Tcl_CreateObjCommand(interp,
122 "sqlite3_blocking_prepare_v2", blocking_prepare_v2_proc, (void *)1, 0);
123 Tcl_CreateObjCommand(interp,
124 "sqlite3_nonblocking_prepare_v2", blocking_prepare_v2_proc, 0, 0);
126 Sqlitetest1_Init(interp);
127 Sqlitetest_mutex_Init(interp);
128 Sqlite3_Init(interp);
130 rc = Tcl_Eval(interp, p->zScript);
131 pRes = Tcl_GetObjResult(interp);
132 pList = Tcl_NewObj();
133 Tcl_IncrRefCount(pList);
134 Tcl_IncrRefCount(pRes);
137 Tcl_ListObjAppendElement(interp, pList, Tcl_NewStringObj("error", -1));
138 Tcl_ListObjAppendElement(interp, pList, pRes);
139 postToParent(p, pList);
140 Tcl_DecrRefCount(pList);
141 pList = Tcl_NewObj();
144 Tcl_ListObjAppendElement(interp, pList, Tcl_NewStringObj("set", -1));
145 Tcl_ListObjAppendElement(interp, pList, Tcl_NewStringObj(p->zVarname, -1));
146 Tcl_ListObjAppendElement(interp, pList, pRes);
147 postToParent(p, pList);
150 Tcl_DecrRefCount(pList);
151 Tcl_DecrRefCount(pRes);
152 Tcl_DeleteInterp(interp);
153 while( Tcl_DoOneEvent(TCL_ALL_EVENTS|TCL_DONT_WAIT) );
155 TCL_THREAD_CREATE_RETURN;
159 ** sqlthread spawn VARNAME SCRIPT
161 ** Spawn a new thread with its own Tcl interpreter and run the
162 ** specified SCRIPT(s) in it. The thread terminates after running
163 ** the script. The result of the script is stored in the variable
166 ** The caller can wait for the script to terminate using [vwait VARNAME].
168 static int sqlthread_spawn(
169 ClientData clientData,
172 Tcl_Obj *CONST objv[]
178 int nVarname; char *zVarname;
179 int nScript; char *zScript;
181 /* Parameters for thread creation */
182 const int nStack = TCL_THREAD_STACK_DEFAULT;
183 const int flags = TCL_THREAD_NOFLAGS;
186 UNUSED_PARAMETER(clientData);
187 UNUSED_PARAMETER(objc);
189 zVarname = Tcl_GetStringFromObj(objv[2], &nVarname);
190 zScript = Tcl_GetStringFromObj(objv[3], &nScript);
192 pNew = (SqlThread *)ckalloc(sizeof(SqlThread)+nVarname+nScript+2);
193 pNew->zVarname = (char *)&pNew[1];
194 pNew->zScript = (char *)&pNew->zVarname[nVarname+1];
195 memcpy(pNew->zVarname, zVarname, nVarname+1);
196 memcpy(pNew->zScript, zScript, nScript+1);
197 pNew->parent = Tcl_GetCurrentThread();
198 pNew->interp = interp;
200 rc = Tcl_CreateThread(&x, tclScriptThread, (void *)pNew, nStack, flags);
202 Tcl_AppendResult(interp, "Error in Tcl_CreateThread()", 0);
203 ckfree((char *)pNew);
211 ** sqlthread parent SCRIPT
213 ** This can be called by spawned threads only. It sends the specified
214 ** script back to the parent thread for execution. The result of
215 ** evaluating the SCRIPT is returned. The parent thread must enter
216 ** the event loop for this to work - otherwise the caller will
217 ** block indefinitely.
219 ** NOTE: At the moment, this doesn't work. FIXME.
221 static int sqlthread_parent(
222 ClientData clientData,
225 Tcl_Obj *CONST objv[]
230 SqlThread *p = (SqlThread *)clientData;
233 UNUSED_PARAMETER(objc);
236 Tcl_AppendResult(interp, "no parent thread", 0);
240 zMsg = Tcl_GetStringFromObj(objv[2], &nMsg);
241 pEvent = (EvalEvent *)ckalloc(sizeof(EvalEvent)+nMsg+1);
242 pEvent->base.nextPtr = 0;
243 pEvent->base.proc = tclScriptEvent;
244 pEvent->zScript = (char *)&pEvent[1];
245 memcpy(pEvent->zScript, zMsg, nMsg+1);
246 pEvent->interp = p->interp;
247 Tcl_ThreadQueueEvent(p->parent, (Tcl_Event *)pEvent, TCL_QUEUE_TAIL);
248 Tcl_ThreadAlert(p->parent);
253 static int xBusy(void *pArg, int nBusy){
254 UNUSED_PARAMETER(pArg);
255 UNUSED_PARAMETER(nBusy);
257 return 1; /* Try again... */
263 ** Open a database handle and return the string representation of
264 ** the pointer value.
266 static int sqlthread_open(
267 ClientData clientData,
270 Tcl_Obj *CONST objv[]
272 int sqlite3TestMakePointerStr(Tcl_Interp *interp, char *zPtr, void *p);
274 const char *zFilename;
278 extern void Md5_Register(sqlite3*);
280 UNUSED_PARAMETER(clientData);
281 UNUSED_PARAMETER(objc);
283 zFilename = Tcl_GetString(objv[2]);
284 rc = sqlite3_open(zFilename, &db);
286 sqlite3_busy_handler(db, xBusy, 0);
288 if( sqlite3TestMakePointerStr(interp, zBuf, db) ) return TCL_ERROR;
289 Tcl_AppendResult(interp, zBuf, 0);
298 ** Return the current thread-id (Tcl_GetCurrentThread()) cast to
301 static int sqlthread_id(
302 ClientData clientData,
305 Tcl_Obj *CONST objv[]
307 Tcl_ThreadId id = Tcl_GetCurrentThread();
308 Tcl_SetObjResult(interp, Tcl_NewIntObj((int)id));
309 UNUSED_PARAMETER(clientData);
310 UNUSED_PARAMETER(objc);
311 UNUSED_PARAMETER(objv);
317 ** Dispatch routine for the sub-commands of [sqlthread].
319 static int sqlthread_proc(
320 ClientData clientData,
323 Tcl_Obj *CONST objv[]
327 Tcl_ObjCmdProc *xProc;
331 {"parent", sqlthread_parent, 1, "SCRIPT"},
332 {"spawn", sqlthread_spawn, 2, "VARNAME SCRIPT"},
333 {"open", sqlthread_open, 1, "DBNAME"},
334 {"id", sqlthread_id, 0, ""},
337 struct SubCommand *pSub;
342 Tcl_WrongNumArgs(interp, 1, objv, "SUB-COMMAND");
346 rc = Tcl_GetIndexFromObjStruct(
347 interp, objv[1], aSub, sizeof(aSub[0]), "sub-command", 0, &iIndex
349 if( rc!=TCL_OK ) return rc;
350 pSub = &aSub[iIndex];
352 if( objc!=(pSub->nArg+2) ){
353 Tcl_WrongNumArgs(interp, 2, objv, pSub->zUsage);
357 return pSub->xProc(clientData, interp, objc, objv);
361 ** The [clock_seconds] command. This is more or less the same as the
362 ** regular tcl [clock seconds], except that it is available in testfixture
363 ** when linked against both Tcl 8.4 and 8.5. Because [clock seconds] is
364 ** implemented as a script in Tcl 8.5, it is not usually available to
367 static int clock_seconds_proc(
368 ClientData clientData,
371 Tcl_Obj *CONST objv[]
375 Tcl_SetObjResult(interp, Tcl_NewIntObj(now.sec));
376 UNUSED_PARAMETER(clientData);
377 UNUSED_PARAMETER(objc);
378 UNUSED_PARAMETER(objv);
382 /*************************************************************************
383 ** This block contains the implementation of the [sqlite3_blocking_step]
384 ** command available to threads created by [sqlthread spawn] commands. It
385 ** is only available on UNIX for now. This is because pthread condition
386 ** variables are used.
388 ** The source code for the C functions sqlite3_blocking_step(),
389 ** blocking_step_notify() and the structure UnlockNotification is
390 ** automatically extracted from this file and used as part of the
391 ** documentation for the sqlite3_unlock_notify() API function. This
392 ** should be considered if these functions are to be extended (i.e. to
393 ** support windows) in the future.
395 #if SQLITE_OS_UNIX && defined(SQLITE_ENABLE_UNLOCK_NOTIFY)
397 /* BEGIN_SQLITE_BLOCKING_STEP */
398 /* This example uses the pthreads API */
402 ** A pointer to an instance of this structure is passed as the user-context
403 ** pointer when registering for an unlock-notify callback.
405 typedef struct UnlockNotification UnlockNotification;
406 struct UnlockNotification {
407 int fired; /* True after unlock event has occured */
408 pthread_cond_t cond; /* Condition variable to wait on */
409 pthread_mutex_t mutex; /* Mutex to protect structure */
413 ** This function is an unlock-notify callback registered with SQLite.
415 static void unlock_notify_cb(void **apArg, int nArg){
417 for(i=0; i<nArg; i++){
418 UnlockNotification *p = (UnlockNotification *)apArg[i];
419 pthread_mutex_lock(&p->mutex);
421 pthread_cond_signal(&p->cond);
422 pthread_mutex_unlock(&p->mutex);
427 ** This function assumes that an SQLite API call (either sqlite3_prepare_v2()
428 ** or sqlite3_step()) has just returned SQLITE_LOCKED. The argument is the
429 ** associated database connection.
431 ** This function calls sqlite3_unlock_notify() to register for an
432 ** unlock-notify callback, then blocks until that callback is delivered
433 ** and returns SQLITE_OK. The caller should then retry the failed operation.
435 ** Or, if sqlite3_unlock_notify() indicates that to block would deadlock
436 ** the system, then this function returns SQLITE_LOCKED immediately. In
437 ** this case the caller should not retry the operation and should roll
438 ** back the current transaction (if any).
440 static int wait_for_unlock_notify(sqlite3 *db){
442 UnlockNotification un;
444 /* Initialize the UnlockNotification structure. */
446 pthread_mutex_init(&un.mutex, 0);
447 pthread_cond_init(&un.cond, 0);
449 /* Register for an unlock-notify callback. */
450 rc = sqlite3_unlock_notify(db, unlock_notify_cb, (void *)&un);
451 assert( rc==SQLITE_LOCKED || rc==SQLITE_OK );
453 /* The call to sqlite3_unlock_notify() always returns either SQLITE_LOCKED
456 ** If SQLITE_LOCKED was returned, then the system is deadlocked. In this
457 ** case this function needs to return SQLITE_LOCKED to the caller so
458 ** that the current transaction can be rolled back. Otherwise, block
459 ** until the unlock-notify callback is invoked, then return SQLITE_OK.
462 pthread_mutex_lock(&un.mutex);
464 pthread_cond_wait(&un.cond, &un.mutex);
466 pthread_mutex_unlock(&un.mutex);
469 /* Destroy the mutex and condition variables. */
470 pthread_cond_destroy(&un.cond);
471 pthread_mutex_destroy(&un.mutex);
477 ** This function is a wrapper around the SQLite function sqlite3_step().
478 ** It functions in the same way as step(), except that if a required
479 ** shared-cache lock cannot be obtained, this function may block waiting for
480 ** the lock to become available. In this scenario the normal API step()
481 ** function always returns SQLITE_LOCKED.
483 ** If this function returns SQLITE_LOCKED, the caller should rollback
484 ** the current transaction (if any) and try again later. Otherwise, the
485 ** system may become deadlocked.
487 int sqlite3_blocking_step(sqlite3_stmt *pStmt){
489 while( SQLITE_LOCKED==(rc = sqlite3_step(pStmt)) ){
490 rc = wait_for_unlock_notify(sqlite3_db_handle(pStmt));
491 if( rc!=SQLITE_OK ) break;
492 sqlite3_reset(pStmt);
498 ** This function is a wrapper around the SQLite function sqlite3_prepare_v2().
499 ** It functions in the same way as prepare_v2(), except that if a required
500 ** shared-cache lock cannot be obtained, this function may block waiting for
501 ** the lock to become available. In this scenario the normal API prepare_v2()
502 ** function always returns SQLITE_LOCKED.
504 ** If this function returns SQLITE_LOCKED, the caller should rollback
505 ** the current transaction (if any) and try again later. Otherwise, the
506 ** system may become deadlocked.
508 int sqlite3_blocking_prepare_v2(
509 sqlite3 *db, /* Database handle. */
510 const char *zSql, /* UTF-8 encoded SQL statement. */
511 int nSql, /* Length of zSql in bytes. */
512 sqlite3_stmt **ppStmt, /* OUT: A pointer to the prepared statement */
513 const char **pz /* OUT: End of parsed string */
516 while( SQLITE_LOCKED==(rc = sqlite3_prepare_v2(db, zSql, nSql, ppStmt, pz)) ){
517 rc = wait_for_unlock_notify(db);
518 if( rc!=SQLITE_OK ) break;
522 /* END_SQLITE_BLOCKING_STEP */
525 ** Usage: sqlite3_blocking_step STMT
527 ** Advance the statement to the next row.
529 static int blocking_step_proc(
533 Tcl_Obj *CONST objv[]
540 Tcl_WrongNumArgs(interp, 1, objv, "STMT");
544 pStmt = (sqlite3_stmt*)sqlite3TestTextToPtr(Tcl_GetString(objv[1]));
545 rc = sqlite3_blocking_step(pStmt);
547 Tcl_SetResult(interp, (char *)sqlite3TestErrorName(rc), 0);
552 ** Usage: sqlite3_blocking_prepare_v2 DB sql bytes ?tailvar?
553 ** Usage: sqlite3_nonblocking_prepare_v2 DB sql bytes ?tailvar?
555 static int blocking_prepare_v2_proc(
559 Tcl_Obj *CONST objv[]
564 const char *zTail = 0;
565 sqlite3_stmt *pStmt = 0;
568 int isBlocking = !(clientData==0);
570 if( objc!=5 && objc!=4 ){
571 Tcl_AppendResult(interp, "wrong # args: should be \"",
572 Tcl_GetString(objv[0]), " DB sql bytes tailvar", 0);
575 if( getDbPointer(interp, Tcl_GetString(objv[1]), &db) ) return TCL_ERROR;
576 zSql = Tcl_GetString(objv[2]);
577 if( Tcl_GetIntFromObj(interp, objv[3], &bytes) ) return TCL_ERROR;
580 rc = sqlite3_blocking_prepare_v2(db, zSql, bytes, &pStmt, &zTail);
582 rc = sqlite3_prepare_v2(db, zSql, bytes, &pStmt, &zTail);
585 assert(rc==SQLITE_OK || pStmt==0);
586 if( zTail && objc>=5 ){
588 bytes = bytes - (zTail-zSql);
590 Tcl_ObjSetVar2(interp, objv[4], 0, Tcl_NewStringObj(zTail, bytes), 0);
594 sprintf(zBuf, "%s ", (char *)sqlite3TestErrorName(rc));
595 Tcl_AppendResult(interp, zBuf, sqlite3_errmsg(db), 0);
600 if( sqlite3TestMakePointerStr(interp, zBuf, pStmt) ) return TCL_ERROR;
601 Tcl_AppendResult(interp, zBuf, 0);
606 #endif /* SQLITE_OS_UNIX && SQLITE_ENABLE_UNLOCK_NOTIFY */
608 ** End of implementation of [sqlite3_blocking_step].
609 ************************************************************************/
612 ** Register commands with the TCL interpreter.
614 int SqlitetestThread_Init(Tcl_Interp *interp){
615 Tcl_CreateObjCommand(interp, "sqlthread", sqlthread_proc, 0, 0);
616 Tcl_CreateObjCommand(interp, "clock_seconds", clock_seconds_proc, 0, 0);
617 #if SQLITE_OS_UNIX && defined(SQLITE_ENABLE_UNLOCK_NOTIFY)
618 Tcl_CreateObjCommand(interp, "sqlite3_blocking_step", blocking_step_proc,0,0);
619 Tcl_CreateObjCommand(interp,
620 "sqlite3_blocking_prepare_v2", blocking_prepare_v2_proc, (void *)1, 0);
621 Tcl_CreateObjCommand(interp,
622 "sqlite3_nonblocking_prepare_v2", blocking_prepare_v2_proc, 0, 0);
627 int SqlitetestThread_Init(Tcl_Interp *interp){