Must hold mutex on the destination during backups. Add documentation to

warn programmers that attempting to use the destination connection during
a backup can lead to deadlock. (CVS 6246)

FossilOrigin-Name: 5f6c06b974f26532264467ace603b6f1f830fba9

manifest

@@ -1,5 +1,5 @@
-C Fixed\spostToParent()\sreturn\stype\s(Tcl_ThreadCreateType)\sin\stest_thread.c\sto\scompile\swith\sMSVC.\s\sRemoved\sa\sfew\scompiler\swarnings.\s\sTest\sharness\schange\sonly.\s(CVS\s6245)
-D 2009-02-03T19:55:20
+C Must\shold\smutex\son\sthe\sdestination\sduring\sbackups.\s\sAdd\sdocumentation\sto\nwarn\sprogrammers\sthat\sattempting\sto\suse\sthe\sdestination\sconnection\sduring\na\sbackup\scan\slead\sto\sdeadlock.\s(CVS\s6246)
+D 2009-02-03T21:13:08
 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0
 F Makefile.in c7a5a30fb6852bd7839b1024e1661da8549878ee
 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@@ -101,7 +101,7 @@ F src/alter.c 0ec29744c36c6e976596ce38c16289ebc5dc94db
 F src/analyze.c c86fd6a1425b22b3a46ce72ad403e4280026364f
 F src/attach.c 81d37d1948f409146a7b22b96998fd90649d1fd3
 F src/auth.c c8b2ab5c8bad4bd90ed7c294694f48269162c627
-F src/backup.c a7605687863424d5d5a7ff8271f0bbcfd4fc0b57
+F src/backup.c cc6c8a1cead94c06a3a6cf55559cc28db0cdd0ac
 F src/bitvec.c 44f7059ac1f874d364b34af31b9617e52223ba75
 F src/btmutex.c 63c5cc4ad5715690767ffcb741e185d7bc35ec1a
 F src/btree.c 800a065686c49a0cdefc933779a750a7c3c0509f
@@ -157,7 +157,7 @@ F src/resolve.c 18dc9f0df1d60048e012ce6632251063e0dd356a
 F src/rowset.c ba9375f37053d422dd76965a9c370a13b6e1aac4
 F src/select.c ae72b604e47092521c4d9ae54e1b1cbeb872a747
 F src/shell.c 8965cf0cd7a7dac39d586a43c97adb00930e025d
-F src/sqlite.h.in d2302ec33804193b3ae4420f0e9d8d5256d36586
+F src/sqlite.h.in 31fa12602f784adea9be66424a2e8b052116736f
 F src/sqlite3ext.h 1db7d63ab5de4b3e6b83dd03d1a4e64fef6d2a17
 F src/sqliteInt.h 73c1d4f9716fe21f202f9d05c4fd9e6281f2636f
 F src/sqliteLimit.h ffe93f5a0c4e7bd13e70cd7bf84cfb5c3465f45d
@@ -700,7 +700,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81
 F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
-P c1e15717ff1b8181ff5fdc800015dadb62135e8c
-R bfe28e383cd4fc45f4b41be1d388e00a
-U shane
-Z 98a8531a64be0030053f61a9ae6ebf89
+P e9475abaf87c0ae2f2bbcbaf0f7ba704f9f50c5f
+R 4da491343e240dc914db6eeb9d9174f9
+U drh
+Z 7058c074c4ac7048a37cd4334c8f24d7

manifest.uuid

@@ -1 +1 @@
-e9475abaf87c0ae2f2bbcbaf0f7ba704f9f50c5f
+5f6c06b974f26532264467ace603b6f1f830fba9

src/backup.c

@@ -12,7 +12,7 @@
 ** This file contains the implementation of the sqlite3_backup_XXX() 
 ** API functions and the related features.
 **
-** $Id: backup.c,v 1.1 2009/02/03 16:51:25 danielk1977 Exp $
+** $Id: backup.c,v 1.2 2009/02/03 21:13:08 drh Exp $
 */
 #include "sqliteInt.h"
 #include "btreeInt.h"
@@ -126,9 +126,12 @@ sqlite3_backup *sqlite3_backup_init(
   sqlite3_backup *p;                    /* Value to return */
 
   /* Lock the source database handle. The destination database
-  ** handle is not locked. The user is required to ensure that no
+  ** handle is not locked in this routine, but it is locked in
+  ** sqlite3_backup_step(). The user is required to ensure that no
   ** other thread accesses the destination handle for the duration
-  ** of the backup operation.
+  ** of the backup operation.  Any attempt to use the destination
+  ** database connection while a backup is in progress may cause
+  ** a malfunction or a deadlock.
   */
   sqlite3_mutex_enter(pSrcDb->mutex);
 
@@ -248,6 +251,7 @@ int sqlite3_backup_step(sqlite3_backup *p, int nPage){
 
   sqlite3_mutex_enter(p->pSrcDb->mutex);
   sqlite3BtreeEnter(p->pSrc);
+  sqlite3_mutex_enter(p->pDestDb->mutex);
 
   rc = p->rc;
   if( rc==SQLITE_OK ){
@@ -403,6 +407,7 @@ int sqlite3_backup_step(sqlite3_backup *p, int nPage){
       p->rc = rc;
     }
   }
+  sqlite3_mutex_leave(p->pDestDb->mutex);
   sqlite3BtreeLeave(p->pSrc);
   sqlite3_mutex_leave(p->pSrcDb->mutex);
   return rc;
@@ -420,6 +425,7 @@ int sqlite3_backup_finish(sqlite3_backup *p){
   sqlite3_mutex_enter(p->pSrcDb->mutex);
   sqlite3BtreeEnter(p->pSrc);
   mutex = p->pSrcDb->mutex;
+  sqlite3_mutex_enter(p->pDestDb->mutex);
 
   /* Detach this backup from the source pager. */
   if( p->pDestDb ){
@@ -439,6 +445,7 @@ int sqlite3_backup_finish(sqlite3_backup *p){
   sqlite3Error(p->pDestDb, rc, 0);
 
   /* Exit the mutexes and free the backup context structure. */
+  sqlite3_mutex_leave(p->pDestDb->mutex);
   sqlite3BtreeLeave(p->pSrc);
   if( p->pDestDb ){
     sqlite3_free(p);
@@ -556,4 +563,3 @@ int sqlite3BtreeCopyFile(Btree *pTo, Btree *pFrom){
   return rc;
 }
 #endif /* SQLITE_OMIT_VACUUM */
-

src/sqlite.h.in

@@ -30,7 +30,7 @@
 ** the version number) and changes its name to "sqlite3.h" as
 ** part of the build process.
 **
-** @(#) $Id: sqlite.h.in,v 1.425 2009/02/03 18:47:23 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.426 2009/02/03 21:13:08 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -6884,7 +6884,9 @@ typedef struct sqlite3_backup sqlite3_backup;
 ** sqlite3_backup_finish(). Unfortunately SQLite does not currently check
 ** for this, if the application does use the destination [database connection]
 ** for some other purpose during a backup operation, things may appear to
-** work correctly but in fact be subtly malfunctioning.
+** work correctly but in fact be subtly malfunctioning.  Use of the
+** destination database connection while a backup is in progress might
+** also cause a mutex deadlock.
 **
 ** Furthermore, if running in [shared cache mode], the application must
 ** guarantee that the shared cache used by the destination database