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"
19 #if defined(INCLUDE_SQLITE_TCL_H)
20 # include "sqlite_tcl.h"
29 #if !defined(_MSC_VER)
34 ** One of these is allocated for each thread created by [sqlthread spawn].
36 typedef struct SqlThread SqlThread
;
38 Tcl_ThreadId parent
; /* Thread id of parent thread */
39 Tcl_Interp
*interp
; /* Parent interpreter */
40 char *zScript
; /* The script to execute. */
41 char *zVarname
; /* Varname in parent script */
45 ** A custom Tcl_Event type used by this module. When the event is
46 ** handled, script zScript is evaluated in interpreter interp. If
47 ** the evaluation throws an exception (returns TCL_ERROR), then the
48 ** error is handled by Tcl_BackgroundError(). If no error occurs,
49 ** the result is simply discarded.
51 typedef struct EvalEvent EvalEvent
;
53 Tcl_Event base
; /* Base class of type Tcl_Event */
54 char *zScript
; /* The script to execute. */
55 Tcl_Interp
*interp
; /* The interpreter to execute it in. */
58 static Tcl_ObjCmdProc sqlthread_proc
;
59 static Tcl_ObjCmdProc clock_seconds_proc
;
60 #if SQLITE_OS_UNIX && defined(SQLITE_ENABLE_UNLOCK_NOTIFY)
61 static Tcl_ObjCmdProc blocking_step_proc
;
62 static Tcl_ObjCmdProc blocking_prepare_v2_proc
;
64 int Sqlitetest1_Init(Tcl_Interp
*);
65 int Sqlite3_Init(Tcl_Interp
*);
67 /* Functions from main.c */
68 extern const char *sqlite3ErrName(int);
70 /* Functions from test1.c */
71 extern void *sqlite3TestTextToPtr(const char *);
72 extern int getDbPointer(Tcl_Interp
*, const char *, sqlite3
**);
73 extern int sqlite3TestMakePointerStr(Tcl_Interp
*, char *, void *);
74 extern int sqlite3TestErrCode(Tcl_Interp
*, sqlite3
*, int);
77 ** Handler for events of type EvalEvent.
79 static int SQLITE_TCLAPI
tclScriptEvent(Tcl_Event
*evPtr
, int flags
){
81 EvalEvent
*p
= (EvalEvent
*)evPtr
;
82 rc
= Tcl_Eval(p
->interp
, p
->zScript
);
84 Tcl_BackgroundError(p
->interp
);
86 UNUSED_PARAMETER(flags
);
91 ** Register an EvalEvent to evaluate the script pScript in the
92 ** parent interpreter/thread of SqlThread p.
94 static void postToParent(SqlThread
*p
, Tcl_Obj
*pScript
){
99 zMsg
= Tcl_GetStringFromObj(pScript
, &nMsg
);
100 pEvent
= (EvalEvent
*)ckalloc(sizeof(EvalEvent
)+nMsg
+1);
101 pEvent
->base
.nextPtr
= 0;
102 pEvent
->base
.proc
= tclScriptEvent
;
103 pEvent
->zScript
= (char *)&pEvent
[1];
104 memcpy(pEvent
->zScript
, zMsg
, nMsg
+1);
105 pEvent
->interp
= p
->interp
;
107 Tcl_ThreadQueueEvent(p
->parent
, (Tcl_Event
*)pEvent
, TCL_QUEUE_TAIL
);
108 Tcl_ThreadAlert(p
->parent
);
112 ** The main function for threads created with [sqlthread spawn].
114 static Tcl_ThreadCreateType
tclScriptThread(ClientData pSqlThread
){
119 SqlThread
*p
= (SqlThread
*)pSqlThread
;
120 extern int Sqlitetest_mutex_Init(Tcl_Interp
*);
122 interp
= Tcl_CreateInterp();
123 Tcl_CreateObjCommand(interp
, "clock_seconds", clock_seconds_proc
, 0, 0);
124 Tcl_CreateObjCommand(interp
, "sqlthread", sqlthread_proc
, pSqlThread
, 0);
125 #if SQLITE_OS_UNIX && defined(SQLITE_ENABLE_UNLOCK_NOTIFY)
126 Tcl_CreateObjCommand(interp
, "sqlite3_blocking_step", blocking_step_proc
,0,0);
127 Tcl_CreateObjCommand(interp
,
128 "sqlite3_blocking_prepare_v2", blocking_prepare_v2_proc
, (void *)1, 0);
129 Tcl_CreateObjCommand(interp
,
130 "sqlite3_nonblocking_prepare_v2", blocking_prepare_v2_proc
, 0, 0);
132 Sqlitetest1_Init(interp
);
133 Sqlitetest_mutex_Init(interp
);
134 Sqlite3_Init(interp
);
136 rc
= Tcl_Eval(interp
, p
->zScript
);
137 pRes
= Tcl_GetObjResult(interp
);
138 pList
= Tcl_NewObj();
139 Tcl_IncrRefCount(pList
);
140 Tcl_IncrRefCount(pRes
);
143 Tcl_ListObjAppendElement(interp
, pList
, Tcl_NewStringObj("error", -1));
144 Tcl_ListObjAppendElement(interp
, pList
, pRes
);
145 postToParent(p
, pList
);
146 Tcl_DecrRefCount(pList
);
147 pList
= Tcl_NewObj();
150 Tcl_ListObjAppendElement(interp
, pList
, Tcl_NewStringObj("set", -1));
151 Tcl_ListObjAppendElement(interp
, pList
, Tcl_NewStringObj(p
->zVarname
, -1));
152 Tcl_ListObjAppendElement(interp
, pList
, pRes
);
153 postToParent(p
, pList
);
156 Tcl_DecrRefCount(pList
);
157 Tcl_DecrRefCount(pRes
);
158 Tcl_DeleteInterp(interp
);
159 while( Tcl_DoOneEvent(TCL_ALL_EVENTS
|TCL_DONT_WAIT
) );
161 TCL_THREAD_CREATE_RETURN
;
165 ** sqlthread spawn VARNAME SCRIPT
167 ** Spawn a new thread with its own Tcl interpreter and run the
168 ** specified SCRIPT(s) in it. The thread terminates after running
169 ** the script. The result of the script is stored in the variable
172 ** The caller can wait for the script to terminate using [vwait VARNAME].
174 static int SQLITE_TCLAPI
sqlthread_spawn(
175 ClientData clientData
,
178 Tcl_Obj
*CONST objv
[]
184 int nVarname
; char *zVarname
;
185 int nScript
; char *zScript
;
187 /* Parameters for thread creation */
188 const int nStack
= TCL_THREAD_STACK_DEFAULT
;
189 const int flags
= TCL_THREAD_NOFLAGS
;
192 UNUSED_PARAMETER(clientData
);
193 UNUSED_PARAMETER(objc
);
195 zVarname
= Tcl_GetStringFromObj(objv
[2], &nVarname
);
196 zScript
= Tcl_GetStringFromObj(objv
[3], &nScript
);
198 pNew
= (SqlThread
*)ckalloc(sizeof(SqlThread
)+nVarname
+nScript
+2);
199 pNew
->zVarname
= (char *)&pNew
[1];
200 pNew
->zScript
= (char *)&pNew
->zVarname
[nVarname
+1];
201 memcpy(pNew
->zVarname
, zVarname
, nVarname
+1);
202 memcpy(pNew
->zScript
, zScript
, nScript
+1);
203 pNew
->parent
= Tcl_GetCurrentThread();
204 pNew
->interp
= interp
;
206 rc
= Tcl_CreateThread(&x
, tclScriptThread
, (void *)pNew
, nStack
, flags
);
208 Tcl_AppendResult(interp
, "Error in Tcl_CreateThread()", 0);
209 ckfree((char *)pNew
);
217 ** sqlthread parent SCRIPT
219 ** This can be called by spawned threads only. It sends the specified
220 ** script back to the parent thread for execution. The result of
221 ** evaluating the SCRIPT is returned. The parent thread must enter
222 ** the event loop for this to work - otherwise the caller will
223 ** block indefinitely.
225 ** NOTE: At the moment, this doesn't work. FIXME.
227 static int SQLITE_TCLAPI
sqlthread_parent(
228 ClientData clientData
,
231 Tcl_Obj
*CONST objv
[]
236 SqlThread
*p
= (SqlThread
*)clientData
;
239 UNUSED_PARAMETER(objc
);
242 Tcl_AppendResult(interp
, "no parent thread", 0);
246 zMsg
= Tcl_GetStringFromObj(objv
[2], &nMsg
);
247 pEvent
= (EvalEvent
*)ckalloc(sizeof(EvalEvent
)+nMsg
+1);
248 pEvent
->base
.nextPtr
= 0;
249 pEvent
->base
.proc
= tclScriptEvent
;
250 pEvent
->zScript
= (char *)&pEvent
[1];
251 memcpy(pEvent
->zScript
, zMsg
, nMsg
+1);
252 pEvent
->interp
= p
->interp
;
253 Tcl_ThreadQueueEvent(p
->parent
, (Tcl_Event
*)pEvent
, TCL_QUEUE_TAIL
);
254 Tcl_ThreadAlert(p
->parent
);
259 static int xBusy(void *pArg
, int nBusy
){
260 UNUSED_PARAMETER(pArg
);
261 UNUSED_PARAMETER(nBusy
);
263 return 1; /* Try again... */
269 ** Open a database handle and return the string representation of
270 ** the pointer value.
272 static int SQLITE_TCLAPI
sqlthread_open(
273 ClientData clientData
,
276 Tcl_Obj
*CONST objv
[]
278 int sqlite3TestMakePointerStr(Tcl_Interp
*interp
, char *zPtr
, void *p
);
280 const char *zFilename
;
283 extern int Md5_Register(sqlite3
*,char**,const sqlite3_api_routines
*);
285 UNUSED_PARAMETER(clientData
);
286 UNUSED_PARAMETER(objc
);
288 zFilename
= Tcl_GetString(objv
[2]);
289 sqlite3_open(zFilename
, &db
);
290 /* BEGIN SQLCIPHER */
291 #ifdef SQLITE_HAS_CODEC
296 zKey
= Tcl_GetStringFromObj(objv
[3], &nKey
);
297 rc
= sqlite3_key(db
, zKey
, nKey
);
299 char *zErrMsg
= sqlite3_mprintf("error %d: %s", rc
, sqlite3_errmsg(db
));
301 Tcl_AppendResult(interp
, zErrMsg
, (char*)0);
302 sqlite3_free(zErrMsg
);
308 Md5_Register(db
, 0, 0);
309 sqlite3_busy_handler(db
, xBusy
, 0);
311 if( sqlite3TestMakePointerStr(interp
, zBuf
, db
) ) return TCL_ERROR
;
312 Tcl_AppendResult(interp
, zBuf
, 0);
321 ** Return the current thread-id (Tcl_GetCurrentThread()) cast to
324 static int SQLITE_TCLAPI
sqlthread_id(
325 ClientData clientData
,
328 Tcl_Obj
*CONST objv
[]
330 Tcl_ThreadId id
= Tcl_GetCurrentThread();
331 Tcl_SetObjResult(interp
, Tcl_NewIntObj(SQLITE_PTR_TO_INT(id
)));
332 UNUSED_PARAMETER(clientData
);
333 UNUSED_PARAMETER(objc
);
334 UNUSED_PARAMETER(objv
);
340 ** Dispatch routine for the sub-commands of [sqlthread].
342 static int SQLITE_TCLAPI
sqlthread_proc(
343 ClientData clientData
,
346 Tcl_Obj
*CONST objv
[]
350 Tcl_ObjCmdProc
*xProc
;
354 {"parent", sqlthread_parent
, 1, "SCRIPT"},
355 {"spawn", sqlthread_spawn
, 2, "VARNAME SCRIPT"},
356 {"open", sqlthread_open
, 1, "DBNAME"},
357 {"id", sqlthread_id
, 0, ""},
360 struct SubCommand
*pSub
;
365 Tcl_WrongNumArgs(interp
, 1, objv
, "SUB-COMMAND");
369 rc
= Tcl_GetIndexFromObjStruct(
370 interp
, objv
[1], aSub
, sizeof(aSub
[0]), "sub-command", 0, &iIndex
372 if( rc
!=TCL_OK
) return rc
;
373 pSub
= &aSub
[iIndex
];
375 if( objc
<(pSub
->nArg
+2) ){
376 Tcl_WrongNumArgs(interp
, 2, objv
, pSub
->zUsage
);
380 return pSub
->xProc(clientData
, interp
, objc
, objv
);
384 ** The [clock_seconds] command. This is more or less the same as the
385 ** regular tcl [clock seconds], except that it is available in testfixture
386 ** when linked against both Tcl 8.4 and 8.5. Because [clock seconds] is
387 ** implemented as a script in Tcl 8.5, it is not usually available to
390 static int SQLITE_TCLAPI
clock_seconds_proc(
391 ClientData clientData
,
394 Tcl_Obj
*CONST objv
[]
398 Tcl_SetObjResult(interp
, Tcl_NewIntObj(now
.sec
));
399 UNUSED_PARAMETER(clientData
);
400 UNUSED_PARAMETER(objc
);
401 UNUSED_PARAMETER(objv
);
406 ** The [clock_milliseconds] command. This is more or less the same as the
407 ** regular tcl [clock milliseconds].
409 static int SQLITE_TCLAPI
clock_milliseconds_proc(
410 ClientData clientData
,
413 Tcl_Obj
*CONST objv
[]
417 Tcl_SetObjResult(interp
, Tcl_NewWideIntObj(
418 ((Tcl_WideInt
)now
.sec
* 1000) + (now
.usec
/ 1000)
420 UNUSED_PARAMETER(clientData
);
421 UNUSED_PARAMETER(objc
);
422 UNUSED_PARAMETER(objv
);
426 /*************************************************************************
427 ** This block contains the implementation of the [sqlite3_blocking_step]
428 ** command available to threads created by [sqlthread spawn] commands. It
429 ** is only available on UNIX for now. This is because pthread condition
430 ** variables are used.
432 ** The source code for the C functions sqlite3_blocking_step(),
433 ** blocking_step_notify() and the structure UnlockNotification is
434 ** automatically extracted from this file and used as part of the
435 ** documentation for the sqlite3_unlock_notify() API function. This
436 ** should be considered if these functions are to be extended (i.e. to
437 ** support windows) in the future.
439 #if SQLITE_OS_UNIX && defined(SQLITE_ENABLE_UNLOCK_NOTIFY)
441 /* BEGIN_SQLITE_BLOCKING_STEP */
442 /* This example uses the pthreads API */
446 ** A pointer to an instance of this structure is passed as the user-context
447 ** pointer when registering for an unlock-notify callback.
449 typedef struct UnlockNotification UnlockNotification
;
450 struct UnlockNotification
{
451 int fired
; /* True after unlock event has occurred */
452 pthread_cond_t cond
; /* Condition variable to wait on */
453 pthread_mutex_t mutex
; /* Mutex to protect structure */
457 ** This function is an unlock-notify callback registered with SQLite.
459 static void unlock_notify_cb(void **apArg
, int nArg
){
461 for(i
=0; i
<nArg
; i
++){
462 UnlockNotification
*p
= (UnlockNotification
*)apArg
[i
];
463 pthread_mutex_lock(&p
->mutex
);
465 pthread_cond_signal(&p
->cond
);
466 pthread_mutex_unlock(&p
->mutex
);
471 ** This function assumes that an SQLite API call (either sqlite3_prepare_v2()
472 ** or sqlite3_step()) has just returned SQLITE_LOCKED. The argument is the
473 ** associated database connection.
475 ** This function calls sqlite3_unlock_notify() to register for an
476 ** unlock-notify callback, then blocks until that callback is delivered
477 ** and returns SQLITE_OK. The caller should then retry the failed operation.
479 ** Or, if sqlite3_unlock_notify() indicates that to block would deadlock
480 ** the system, then this function returns SQLITE_LOCKED immediately. In
481 ** this case the caller should not retry the operation and should roll
482 ** back the current transaction (if any).
484 static int wait_for_unlock_notify(sqlite3
*db
){
486 UnlockNotification un
;
488 /* Initialize the UnlockNotification structure. */
490 pthread_mutex_init(&un
.mutex
, 0);
491 pthread_cond_init(&un
.cond
, 0);
493 /* Register for an unlock-notify callback. */
494 rc
= sqlite3_unlock_notify(db
, unlock_notify_cb
, (void *)&un
);
495 assert( rc
==SQLITE_LOCKED
|| rc
==SQLITE_OK
);
497 /* The call to sqlite3_unlock_notify() always returns either SQLITE_LOCKED
500 ** If SQLITE_LOCKED was returned, then the system is deadlocked. In this
501 ** case this function needs to return SQLITE_LOCKED to the caller so
502 ** that the current transaction can be rolled back. Otherwise, block
503 ** until the unlock-notify callback is invoked, then return SQLITE_OK.
506 pthread_mutex_lock(&un
.mutex
);
508 pthread_cond_wait(&un
.cond
, &un
.mutex
);
510 pthread_mutex_unlock(&un
.mutex
);
513 /* Destroy the mutex and condition variables. */
514 pthread_cond_destroy(&un
.cond
);
515 pthread_mutex_destroy(&un
.mutex
);
521 ** This function is a wrapper around the SQLite function sqlite3_step().
522 ** It functions in the same way as step(), except that if a required
523 ** shared-cache lock cannot be obtained, this function may block waiting for
524 ** the lock to become available. In this scenario the normal API step()
525 ** function always returns SQLITE_LOCKED.
527 ** If this function returns SQLITE_LOCKED, the caller should rollback
528 ** the current transaction (if any) and try again later. Otherwise, the
529 ** system may become deadlocked.
531 int sqlite3_blocking_step(sqlite3_stmt
*pStmt
){
533 while( SQLITE_LOCKED
==(rc
= sqlite3_step(pStmt
)) ){
534 rc
= wait_for_unlock_notify(sqlite3_db_handle(pStmt
));
535 if( rc
!=SQLITE_OK
) break;
536 sqlite3_reset(pStmt
);
542 ** This function is a wrapper around the SQLite function sqlite3_prepare_v2().
543 ** It functions in the same way as prepare_v2(), except that if a required
544 ** shared-cache lock cannot be obtained, this function may block waiting for
545 ** the lock to become available. In this scenario the normal API prepare_v2()
546 ** function always returns SQLITE_LOCKED.
548 ** If this function returns SQLITE_LOCKED, the caller should rollback
549 ** the current transaction (if any) and try again later. Otherwise, the
550 ** system may become deadlocked.
552 int sqlite3_blocking_prepare_v2(
553 sqlite3
*db
, /* Database handle. */
554 const char *zSql
, /* UTF-8 encoded SQL statement. */
555 int nSql
, /* Length of zSql in bytes. */
556 sqlite3_stmt
**ppStmt
, /* OUT: A pointer to the prepared statement */
557 const char **pz
/* OUT: End of parsed string */
560 while( SQLITE_LOCKED
==(rc
= sqlite3_prepare_v2(db
, zSql
, nSql
, ppStmt
, pz
)) ){
561 rc
= wait_for_unlock_notify(db
);
562 if( rc
!=SQLITE_OK
) break;
566 /* END_SQLITE_BLOCKING_STEP */
569 ** Usage: sqlite3_blocking_step STMT
571 ** Advance the statement to the next row.
573 static int SQLITE_TCLAPI
blocking_step_proc(
577 Tcl_Obj
*CONST objv
[]
584 Tcl_WrongNumArgs(interp
, 1, objv
, "STMT");
588 pStmt
= (sqlite3_stmt
*)sqlite3TestTextToPtr(Tcl_GetString(objv
[1]));
589 rc
= sqlite3_blocking_step(pStmt
);
591 Tcl_SetResult(interp
, (char *)sqlite3ErrName(rc
), 0);
596 ** Usage: sqlite3_blocking_prepare_v2 DB sql bytes ?tailvar?
597 ** Usage: sqlite3_nonblocking_prepare_v2 DB sql bytes ?tailvar?
599 static int SQLITE_TCLAPI
blocking_prepare_v2_proc(
603 Tcl_Obj
*CONST objv
[]
608 const char *zTail
= 0;
609 sqlite3_stmt
*pStmt
= 0;
612 int isBlocking
= !(clientData
==0);
614 if( objc
!=5 && objc
!=4 ){
615 Tcl_AppendResult(interp
, "wrong # args: should be \"",
616 Tcl_GetString(objv
[0]), " DB sql bytes tailvar", 0);
619 if( getDbPointer(interp
, Tcl_GetString(objv
[1]), &db
) ) return TCL_ERROR
;
620 zSql
= Tcl_GetString(objv
[2]);
621 if( Tcl_GetIntFromObj(interp
, objv
[3], &bytes
) ) return TCL_ERROR
;
624 rc
= sqlite3_blocking_prepare_v2(db
, zSql
, bytes
, &pStmt
, &zTail
);
626 rc
= sqlite3_prepare_v2(db
, zSql
, bytes
, &pStmt
, &zTail
);
629 assert(rc
==SQLITE_OK
|| pStmt
==0);
630 if( zTail
&& objc
>=5 ){
632 bytes
= bytes
- (zTail
-zSql
);
634 Tcl_ObjSetVar2(interp
, objv
[4], 0, Tcl_NewStringObj(zTail
, bytes
), 0);
638 sqlite3_snprintf(sizeof(zBuf
), zBuf
, "%s ", (char *)sqlite3ErrName(rc
));
639 Tcl_AppendResult(interp
, zBuf
, sqlite3_errmsg(db
), 0);
644 if( sqlite3TestMakePointerStr(interp
, zBuf
, pStmt
) ) return TCL_ERROR
;
645 Tcl_AppendResult(interp
, zBuf
, 0);
650 #endif /* SQLITE_OS_UNIX && SQLITE_ENABLE_UNLOCK_NOTIFY */
652 ** End of implementation of [sqlite3_blocking_step].
653 ************************************************************************/
656 ** Register commands with the TCL interpreter.
658 int SqlitetestThread_Init(Tcl_Interp
*interp
){
660 int (*xProc
)(void*, Tcl_Interp
*, int, Tcl_Obj
*const*);
664 { sqlthread_proc
, "sqlthread", 0 },
665 { clock_seconds_proc
, "clock_second", 0 },
666 { clock_milliseconds_proc
, "clock_milliseconds", 0 },
667 #if SQLITE_OS_UNIX && defined(SQLITE_ENABLE_UNLOCK_NOTIFY)
668 { blocking_step_proc
, "sqlite3_blocking_step", 0 },
669 { blocking_prepare_v2_proc
, "sqlite3_blocking_prepare_v2", 1 },
670 { blocking_prepare_v2_proc
, "sqlite3_nonblocking_prepare_v2", 0 },
675 for(ii
=0; ii
<sizeof(aCmd
)/sizeof(aCmd
[0]); ii
++){
676 void *p
= SQLITE_INT_TO_PTR(aCmd
[ii
].iCtx
);
677 Tcl_CreateObjCommand(interp
, aCmd
[ii
].zName
, aCmd
[ii
].xProc
, p
, 0);
682 int SqlitetestThread_Init(Tcl_Interp
*interp
){